@dotdrelle/wiki-manager 0.12.7 → 0.12.8

package/README.md

@@ -36,6 +36,44 @@ 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
+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`.
+
+### 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.
+
+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 +92,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 +192,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 +420,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,12 @@ 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
 
-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.8",
   "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';
@@ -735,6 +735,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,6 +790,12 @@ 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;

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.12.7",
-  "commit": "0bab10f"
+  "version": "0.12.8",
+  "commit": "eefd59f"
 }

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; the
+// user only has to fill in tokens/keys.
+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(`scaffold: created ${created.join(' and ')} in ${managerStateDir()} from packaged example(s) — fill in tokens/keys (WIKI_WORKSPACES_DIR, *_MCP_AUTH_TOKEN…) before starting agents.`);
+  }
+  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.8';
 
 function envValue(key) {
   const filePath = managerEnvFile();

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 "")"