@dotdrelle/wiki-manager 0.12.7 → 0.12.9

package/README.md

@@ -36,6 +36,52 @@ everything — either with the mouse in a browser, or by talking to an assistant
 A **workspace** = a project. Each project is isolated: its documents, settings,
 and results never get mixed up with the others.
 
+## Installation and command modes
+
+The package can be installed either locally in a project or globally. The
+command used afterwards depends on the installation mode.
+
+### Local installation
+
+Use a local installation when the manager should be pinned in a project's
+`package.json`:
+
+```bash
+npm install @dotdrelle/wiki-manager
+npm approve-scripts bun  # only when npm reports that Bun's postinstall is pending
+npx wiki-manager
+npx wiki-workspace --help
+```
+
+`npm install` does not add `wiki-manager` or `wiki-workspace` to the shell's
+global `PATH`. Run local executables with `npx` (or `npm exec wiki-manager` and
+`npm exec wiki-workspace`). Bun is installed automatically as a package runtime;
+you do not need to add `~/.bun/bin` to `PATH`. Recent npm versions may require
+the explicit `npm approve-scripts bun` security approval shown above before the
+first launch.
+
+### Global installation
+
+Use a global installation when the commands should be available directly from
+any directory:
+
+```bash
+npm install --global @dotdrelle/wiki-manager
+wiki-manager
+wiki-workspace --help
+```
+
+The global installation also installs the required Bun runtime. A separately
+installed Bun remains supported, but is not required. If npm blocks Bun's
+installation script, reinstall with:
+
+```bash
+npm install --global --allow-scripts=bun @dotdrelle/wiki-manager
+```
+
+In both modes, launch the commands from the directory that should hold the
+manager state (`workspaces/`, `.env`, and `mcp.endpoints.json`).
+
 ## Functional overview
 
 The diagram below shows the whole picture at a glance: how **inputs** (external
@@ -54,14 +100,17 @@ chat** — all on the **shipped example**, with **no external source to
 configure**. External agents (Confluence, mail…) come later, only when you plug
 in real sources.
 
-> **Prerequisites:** Docker running and Node ≥ 22.
+> **Prerequisites:** Docker running and Node ≥ 22. Bun is installed with the npm
+> package.
 
-**1 — Install once, pick a home folder.**
+**1 — Install globally, pick a home folder.**
 The manager keeps its state (workspaces, `.env`, endpoints) in the directory
-where you launch it, so give it a home:
+where you launch it, so give it a home. This quick start uses the global mode;
+see [Installation and command modes](#installation-and-command-modes) for the
+local `npm install` + `npx` mode.
 
 ```bash
-npm i -g @dotdrelle/wiki-manager
+npm install --global @dotdrelle/wiki-manager
 mkdir -p ~/llm-wiki && cd ~/llm-wiki      # all manager state lives here
 ```
 
@@ -151,7 +200,7 @@ wiki-workspace wiki demo build            # or, in the shell: /skills run pipeli
 That's the whole loop. Next: the four ways to use it and how to configure the
 external agents (CME & co.) live in [docs/usage.md](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/usage.md); the detailed
 story is in [The journey](#the-journey-from-first-launch-to-first-result); and
-installing from source is in [Initial Setup](#initial-setup).
+installing from source is in [Installing from source](#installing-from-source).
 
 ## The journey: from first launch to first result
 
@@ -379,15 +428,15 @@ root `.env`; the wiki's **LLM keys** live in each workspace `.wikirc.yaml`.
 See the full, field-by-field reference in
 **[docs/configuration.md](https://raw.githubusercontent.com/dotdrelle/llm-wiki-manager/main/docs/configuration.md)**.
 
-## Initial Setup
+## Installing from source
 
 ```bash
 corepack enable
 pnpm install
 ```
 
-When installed through `npm`/`npx`/`bun`, `wiki-manager` keeps its state outside
-the package, in the directory where the command is launched:
+Whether installed locally, globally, or from source, `wiki-manager` keeps its
+state outside the package, in the directory where the command is launched:
 
 ```text
 ./workspaces/            # workspace registry

package/bin/wiki-manager

@@ -39,7 +39,26 @@ if [[ -n "$CACERT_PATH" ]]; then
   export CURL_CA_BUNDLE="$CACERT_PATH"
 fi
 
+SCRIPT_SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SCRIPT_SOURCE" ]]; do
+  SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+  SCRIPT_TARGET="$(readlink "$SCRIPT_SOURCE")"
+  if [[ "$SCRIPT_TARGET" = /* ]]; then
+    SCRIPT_SOURCE="$SCRIPT_TARGET"
+  else
+    SCRIPT_SOURCE="$SCRIPT_DIR/$SCRIPT_TARGET"
+  fi
+done
+BIN_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+PACKAGE_DIR="$(cd "$BIN_DIR/.." && pwd)"
+
 BUN_BIN="$(command -v bun 2>/dev/null || true)"
+if [[ -z "$BUN_BIN" && -x "$PACKAGE_DIR/node_modules/.bin/bun" ]]; then
+  BUN_BIN="$PACKAGE_DIR/node_modules/.bin/bun"
+fi
+if [[ -z "$BUN_BIN" && -x "$PACKAGE_DIR/../../.bin/bun" ]]; then
+  BUN_BIN="$PACKAGE_DIR/../../.bin/bun"
+fi
 if [[ -z "$BUN_BIN" && -n "${BUN_INSTALL:-}" && -x "$BUN_INSTALL/bin/bun" ]]; then
   BUN_BIN="$BUN_INSTALL/bin/bun"
 fi
@@ -49,20 +68,19 @@ fi
 if [[ -z "$BUN_BIN" ]]; then
   printf '%s\n' \
     'wiki-manager requires Bun >= 1.2.' \
-    'Install Bun from https://bun.sh/docs/installation or add it to PATH.' >&2
+    'Reinstall @dotdrelle/wiki-manager or install Bun from https://bun.sh/docs/installation.' >&2
   exit 127
 fi
+if ! "$BUN_BIN" --version >/dev/null 2>&1; then
+  printf '%s\n' \
+    'The bundled Bun runtime is installed but not initialized.' \
+    'Local install:  npm approve-scripts bun' \
+    'Global install: npm install -g --allow-scripts=bun @dotdrelle/wiki-manager' >&2
+  exit 126
+fi
 
-SCRIPT_SOURCE="${BASH_SOURCE[0]}"
-while [[ -L "$SCRIPT_SOURCE" ]]; do
-  SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
-  SCRIPT_TARGET="$(readlink "$SCRIPT_SOURCE")"
-  if [[ "$SCRIPT_TARGET" = /* ]]; then
-    SCRIPT_SOURCE="$SCRIPT_TARGET"
-  else
-    SCRIPT_SOURCE="$SCRIPT_DIR/$SCRIPT_TARGET"
-  fi
-done
-BIN_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+if [[ ${#ARGS[@]} -eq 0 ]]; then
+  exec "$BUN_BIN" "$BIN_DIR/wiki-manager.js"
+fi
 
 exec "$BUN_BIN" "$BIN_DIR/wiki-manager.js" "${ARGS[@]}"

package/docker-compose.yml

@@ -55,7 +55,6 @@ services:
       - CME_MCP_AUTH_TOKEN
       - DOCUMENTS_MCP_AUTH_TOKEN
       - MAILER_MCP_AUTH_TOKEN
-      - ATLASSIAN_MCP_AUTH_TOKEN
       - WORKSPACE_NAME
       - DOCUMENT_INPUT_DIR=/documents/input
       - DOCUMENT_UPLOADS_DIR=/documents/uploads

package/mcp.endpoints.example.json

@@ -30,12 +30,6 @@
       "headers": {
         "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}"
       }
-    },
-    "atlassian": {
-      "url": "http://host.docker.internal:9000/mcp",
-      "headers": {
-        "Authorization": "Bearer ${ATLASSIAN_MCP_AUTH_TOKEN}"
-      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.12.7",
+  "version": "0.12.9",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -49,6 +49,7 @@
     "@langchain/langgraph": "^1.3.2",
     "@opentui/core": "^0.3.2",
     "@opentui/solid": "^0.3.2",
+    "bun": "^1.3.14",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
     "openai": "^6.42.0",

package/src/cli/wiki-manager.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadManagerEnv } from '../core/env.js';
+import { ensureManagerScaffold, loadManagerEnv } from '../core/env.js';
 loadManagerEnv();
 import { createAgentGraph } from '../agent/graph.js';
 import { handleSlashCommand, printHelp, printVersion, refreshMcpRuntimeStatus } from '../commands/slash.js';
@@ -677,6 +677,9 @@ async function runRuntime(argv, agent) {
     port,
     store,
     getContext: getWorkspaceContext,
+    listActiveRuns: () => [...contexts.values()]
+      .filter((context) => context?.running)
+      .map((context) => ({ workspace: context.workspace ?? null, runId: context.currentRunId ?? null })),
     run: executeRun,
     cancel: (context) => emitRuntimeLog(context.session, 'runtime: cancel requested'),
     resume: ({ workspace }) => recoverRuntime({ workspace, manual: true }),
@@ -735,6 +738,8 @@ async function runRuntime(argv, agent) {
 
 export async function runCli(argv) {
   if (argv[0] === 'runtime') {
+    const scaffolded = ensureManagerScaffold({ log: (message) => console.log(`[wiki-manager] ${message}`) });
+    if (scaffolded.length > 0) loadManagerEnv();
     const agent = createAgentGraph();
     await runRuntime(argv.slice(1), agent);
     return;
@@ -788,17 +793,29 @@ export async function runCli(argv) {
       throw new Error('Interactive TUI requires Bun. Run: bun ./bin/wiki-manager.js');
     }
     const { runOpenTuiShell, runStartupWizard } = await import('../shell/tui.tsx');
+    // Fresh directory → copy mcp.endpoints.json/.env from the packaged
+    // examples so external agents (cme, mailer, documents) connect out of
+    // the box. Done here (and in `runtime`), NOT at import time: --version
+    // in a random cwd must not litter files.
+    const scaffolded = ensureManagerScaffold({ log: (message) => console.log(`[wiki-manager] ${message}`) });
+    if (scaffolded.length > 0) loadManagerEnv();
     const gaps = await runChecks();
     if (gaps.length > 0) await runStartupWizard(gaps);
     let runtime = null;
     try {
       const { ensureRuntime } = await import('../runtime/lifecycle.js');
-      runtime = await ensureRuntime();
+      // If the manager files were just scaffolded, a pre-existing runtime
+      // predates them: restart it so its sessions load the new endpoints.
+      runtime = await ensureRuntime({ forceRestart: scaffolded.length > 0 });
     } catch (err) {
       runtime = unavailableRuntime(err);
       console.error(`Runtime unavailable: ${runtime.error}`);
     }
     await runOpenTuiShell({ agent, packageJson, runtime });
+    if (runtime?.url) {
+      const { shutdownOwnedRuntime } = await import('../runtime/lifecycle.js');
+      await shutdownOwnedRuntime(runtime, { log: (message) => console.log(`[wiki-manager] ${message}`) });
+    }
     return;
   }
 
@@ -813,4 +830,8 @@ export async function runCli(argv) {
     }
   }
   await runShell({ agent, packageJson, runtime });
+  if (runtime?.url) {
+    const { shutdownOwnedRuntime } = await import('../runtime/lifecycle.js');
+    await shutdownOwnedRuntime(runtime, { log: (message) => console.log(`[wiki-manager] ${message}`) });
+  }
 }

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.12.7",
-  "commit": "0bab10f"
+  "version": "0.12.9",
+  "commit": "286bec2"
 }

package/src/core/env.js

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 export function userManagerDir() {
   return process.cwd();
@@ -31,6 +32,34 @@ export function managerMcpEndpointsFile() {
   return join(managerStateDir(), 'mcp.endpoints.json');
 }
 
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// First-run scaffolding: a fresh install directory has neither
+// mcp.endpoints.json nor .env, so the external agents (cme, mailer,
+// documents) silently never connect — /status shows no agents and Donna has
+// no CME tools to configure anything with. Copy the packaged examples so a
+// fresh directory works out of the box with the default agent ports. Optional
+// credentials can be added later for the external services the user enables.
+export function ensureManagerScaffold({ log = () => {} } = {}) {
+  const created = [];
+  const endpointsFile = managerMcpEndpointsFile();
+  const endpointsExample = join(packageRoot, 'mcp.endpoints.example.json');
+  if (!existsSync(endpointsFile) && existsSync(endpointsExample)) {
+    copyFileSync(endpointsExample, endpointsFile);
+    created.push('mcp.endpoints.json');
+  }
+  const envFile = managerEnvFile();
+  const envExample = join(packageRoot, '.env.example');
+  if (!existsSync(envFile) && existsSync(envExample)) {
+    copyFileSync(envExample, envFile);
+    created.push('.env');
+  }
+  if (created.length > 0) {
+    log(`configuration initialized successfully in ${managerStateDir()} — created ${created.join(' and ')} from packaged defaults. Optional credentials can be added later for external services.`);
+  }
+  return created;
+}
+
 // Single source of truth for where `.agents-data` lives, shared by the
 // manager's own document intake and by the host path it mounts into agent
 // containers — keeping them in sync avoids the two silently drifting apart.

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.12.7';
+const WIKI_MANAGER_VERSION = '0.12.9';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/wikiSetup.js

@@ -3,6 +3,7 @@ import { readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import { patchWikircProfile } from './wikirc.js';
+import { managerEnvFile, managerMcpEndpointsFile } from './env.js';
 import { createWorkspace, findWorkspace, isValidWorkspaceName, listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
@@ -39,6 +40,13 @@ export async function startAgents(options = {}) {
       env: {
         ...process.env,
         WIKI_WORKSPACES_DIR: workspacesDir(),
+        // cwd is the npm package root (the script and compose files live
+        // there), so the manager files MUST be pinned explicitly: without
+        // these, wiki-workspace resolved .env and mcp.endpoints.json against
+        // $PWD and generated agent tokens into the PACKAGE directory — the
+        // user's .env stayed empty on a fresh install.
+        WIKI_MANAGER_ENV_FILE: managerEnvFile(),
+        WIKI_MANAGER_ENDPOINTS_FILE: managerMcpEndpointsFile(),
       },
       timeout: options.timeout ?? 180_000,
       maxBuffer: options.maxBuffer ?? 1024 * 1024 * 8,

package/src/runtime/lifecycle.js

@@ -39,6 +39,7 @@ export async function ensureRuntime({
   stateDir = process.env.WIKI_MANAGER_STATE_DIR ?? defaultRuntimeStateDir(),
   url = process.env.WIKI_MANAGER_RUNTIME_URL ?? `http://127.0.0.1:${port}`,
   timeoutMs = 5000,
+  forceRestart = false,
 } = {}) {
   const auth = resolveRuntimeAuthToken({ host, stateDir });
   if (auth.token) process.env.WIKI_MANAGER_RUNTIME_TOKEN = auth.token;
@@ -46,7 +47,11 @@ export async function ensureRuntime({
   if (existing) {
     const expectedCacertPath = activeCacertPath();
     const actualCacertPath = existing.cacertPath ? resolve(existing.cacertPath) : null;
-    if (actualCacertPath === expectedCacertPath) {
+    // forceRestart: the caller knows the manager configuration just changed
+    // (e.g. mcp.endpoints.json scaffolded on first run) — a runtime started
+    // BEFORE that only knows the old endpoints and would keep answering
+    // without the agents until manually restarted.
+    if (!forceRestart && actualCacertPath === expectedCacertPath) {
       return { url, started: false, health: existing, token: auth.token, tokenPath: auth.tokenPath };
     }
     await postRuntimeShutdown({ url, token: auth.token });
@@ -99,3 +104,28 @@ export async function runtimeHealthOrNull(url = runtimeUrlFromEnv(), token = run
     return null;
   }
 }
+
+// Contract with the user: the shell OWNS the runtime it started — leaving it
+// alive after exit produced zombie runtimes running yesterday's code and
+// yesterday's endpoints. Nuance preserved: if a run is active anywhere, the
+// runtime is left alive so the run survives the shell (that promise stays).
+export async function shutdownOwnedRuntime(runtime, { log = () => {} } = {}) {
+  if (!runtime?.url || !runtime?.started) return { action: 'kept', reason: 'not_owned' };
+  try {
+    const health = await runtimeHealthOrNull(runtime.url, runtime.token);
+    if (!health) return { action: 'kept', reason: 'unreachable' };
+    const activeRuns = Array.isArray(health.activeRuns) ? health.activeRuns : [];
+    if (activeRuns.length > 0) {
+      const labels = activeRuns
+        .map((run) => [run.workspace, run.runId ? String(run.runId).slice(0, 8) : null].filter(Boolean).join('/'))
+        .join(', ');
+      log(`runtime laissé actif : run en cours (${labels}) — il survivra à ce shell ; relance wiki-manager pour le retrouver.`);
+      return { action: 'kept', reason: 'run_active', activeRuns };
+    }
+    await postRuntimeShutdown({ url: runtime.url, token: runtime.token });
+    log('runtime arrêté (démarré par ce shell, aucun run en cours).');
+    return { action: 'shutdown' };
+  } catch (err) {
+    return { action: 'error', reason: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/runtime/server.js

@@ -20,6 +20,7 @@ export function startRuntimeServer({
   approve,
   configProfiles,
   useConfigProfile,
+  listActiveRuns = null,
   exitOnShutdown = process.env.WIKI_MANAGER_RUNTIME_CHILD === '1',
 } = {}) {
   const clients = new Set();
@@ -52,10 +53,14 @@ export function startRuntimeServer({
       if (request.method === 'GET' && url.pathname === '/health') {
         const workspace = workspaceFromUrl(url);
         const context = workspace ? await resolveContext({ workspace }) : null;
+        // activeRuns spans ALL workspace contexts: the shell uses it at exit
+        // to decide whether shutting down its own runtime would kill work.
+        const activeRuns = typeof listActiveRuns === 'function' ? listActiveRuns() : [];
         sendJson(response, 200, {
           ok: true,
           status: context?.running ? 'running' : 'idle',
           workspace: context?.workspace ?? workspace ?? null,
+          activeRuns,
           dbPath: store.dbPath,
           cacertPath: activeCacertPath(),
           nodeExtraCaCerts: process.env.NODE_EXTRA_CA_CERTS ?? null,

package/src/runtime/server.test.js

@@ -1396,3 +1396,31 @@ test('runtime server answers control messages posted to /run during an active ru
     await handle.close();
   }
 });
+
+test('runtime health reports active runs across workspaces', async (t) => {
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: { dbPath: ':memory:', getState: () => ({ status: 'idle' }), listEvents: () => [] },
+      session: {},
+      // The shell reads this at exit: shutting down its own runtime must not
+      // kill a run that is supposed to survive the shell.
+      listActiveRuns: () => [{ workspace: 'juno', runId: 'run-1234abcd' }],
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const health = await (await fetch(`http://127.0.0.1:${handle.port}/health`)).json();
+    assert.deepEqual(health.activeRuns, [{ workspace: 'juno', runId: 'run-1234abcd' }]);
+  } finally {
+    await handle.close();
+  }
+});

package/wiki-workspace

@@ -228,6 +228,12 @@ agents_compose() {
         shift
       fi
       [[ $# -eq 0 ]] || die "agents up accepts only --pull"
+      ensure_agent_tokens
+      ensure_endpoints_file
+      # The .env may have just been created above — recompute the env-file
+      # flag so freshly generated tokens reach the containers on first run.
+      compose_env_args=()
+      [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
       mkdir -p "$agents_data_dir/cme" "$agents_data_dir/documents/input" "$agents_data_dir/documents/output" "$agents_data_dir/documents/uploads"
       mkdir -p "$workspaces_root"
       $do_pull && _agents_dc pull
@@ -382,6 +388,33 @@ ensure_runtime_node() {
   [[ "$major" =~ ^[0-9]+$ && "$major" -ge 22 ]] || die "runtime requires Node.js 22+ for node:sqlite; $node_bin is Node $version"
 }
 
+ensure_agent_tokens() {
+  # The external agents (cme, documents, mailer) authenticate with tokens
+  # from the manager .env — generate any missing one, exactly like the
+  # workspace and runtime tokens are generated. Leaving them empty made a
+  # fresh install start agents nobody could talk to.
+  local key token
+  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN MAILER_MCP_AUTH_TOKEN; do
+    token="$(env_value "$MANAGER_ENV_FILE" "$key" "")"
+    if [[ -z "$token" ]]; then
+      token="$(generate_token)"
+      mkdir -p "$(dirname "$MANAGER_ENV_FILE")"
+      set_env_value "$MANAGER_ENV_FILE" "$key" "$token"
+      printf 'Generated %s in %s\n' "$key" "$MANAGER_ENV_FILE"
+    fi
+  done
+}
+
+ensure_endpoints_file() {
+  # Without mcp.endpoints.json the shell never connects to the agents it
+  # just started (and `agents status` refuses to run). Seed it from the
+  # packaged example; the \${VAR} placeholders resolve against the .env.
+  if [[ ! -f "$MANAGER_ENDPOINTS_FILE" && -f "$ROOT_DIR/mcp.endpoints.example.json" ]]; then
+    cp "$ROOT_DIR/mcp.endpoints.example.json" "$MANAGER_ENDPOINTS_FILE"
+    printf 'Created %s from packaged example\n' "$MANAGER_ENDPOINTS_FILE"
+  fi
+}
+
 ensure_manager_runtime_token() {
   local token
   token="$(env_value "$MANAGER_ENV_FILE" WIKI_MANAGER_RUNTIME_TOKEN "")"