logseq-graph-living-atlas 0.1.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,138 @@
+# Troubleshooting
+
+## `npx logseq-graph-living-atlas` Is Not Found
+
+Confirm npm can see the package:
+
+```bash
+npm view logseq-graph-living-atlas version
+```
+
+If the package is not available yet, run from source:
+
+```bash
+git clone https://github.com/johnschieferleuhlenbrock/logseq-graph-living-atlas.git
+cd logseq-graph-living-atlas
+npm install
+npm run demo
+```
+
+## Missing `pages/`
+
+`--root` must point at the Logseq graph folder, not the `pages/` folder:
+
+```text
+my-logseq-graph/
+  pages/
+  journals/
+```
+
+Check it with:
+
+```bash
+ls /absolute/path/to/my-logseq-graph/pages
+```
+
+## Port Already In Use
+
+Use another local port:
+
+```bash
+living-atlas --root /absolute/path/to/logseq --port 8790
+```
+
+## `401` From `/api/*`
+
+Real graph reads are token-protected by default. Open the `#token=...` URL printed by the service, or provide your own:
+
+```bash
+LIVING_ATLAS_TOKEN=<random-local-token> living-atlas --root /absolute/path/to/logseq
+```
+
+PowerShell:
+
+```powershell
+$env:LIVING_ATLAS_TOKEN = "<random-local-token>"
+living-atlas --root "D:\LogseqGraph"
+```
+
+For fixture-only local experiments, you can opt out:
+
+```bash
+living-atlas --root /path/to/public-fixture --allow-unauthenticated-read
+```
+
+## Split Dev CORS
+
+When running Vite and the API separately, allow the local Vite origin and open the token URL:
+
+```bash
+LIVING_ATLAS_TOKEN=<random-local-token> npm run dev:api -- --root /absolute/path/to/logseq --allowed-origin http://127.0.0.1:5177
+npm run dev
+```
+
+Open `http://127.0.0.1:5177/#token=<random-local-token>`.
+
+PowerShell:
+
+```powershell
+$env:LIVING_ATLAS_TOKEN = "<random-local-token>"
+npm run dev:api -- --root "D:\LogseqGraph" --allowed-origin http://127.0.0.1:5177
+npm run dev
+```
+
+## MCP Changes Do Not Appear In Atlas
+
+Confirm both processes point at the same graph root:
+
+```bash
+living-atlas --root /absolute/path/to/logseq
+npx logseq-graph-mcp --root /absolute/path/to/logseq --readonly
+```
+
+Atlas does not subscribe to the MCP protocol directly. It sees MCP writes as filesystem changes, so either keep Atlas running with `--watch` or call `POST /api/reindex` after a guarded MCP write. If you use a custom cache path, keep the cache outside the graph folder.
+
+Run the public compatibility smoke when debugging install or path issues:
+
+```bash
+npm run smoke:mcp
+```
+
+## Blank Or Unsupported WebGL
+
+Living Atlas needs WebGL for the cinematic field. If WebGL is unavailable, the app should show the fallback graph-inspection panel with totals, top regions, and high-signal pages.
+
+Try another browser, disable low-power/restricted graphics settings, or run the fixture smoke path:
+
+```bash
+npm run demo
+```
+
+## UI Smoke Test Browser Missing
+
+Install the Playwright browser once:
+
+```bash
+npx playwright install chromium
+```
+
+On Linux CI-like systems:
+
+```bash
+npx playwright install --with-deps chromium
+```
+
+## Safe Bug Reports
+
+Do not attach real graph files, private screenshots, cache files, token URLs, or terminal output containing local paths. Reproduce with the public fixture whenever possible:
+
+```bash
+npm run demo
+npm run test:ui
+```
+
+For API-shaped bug reports from a real graph, request redacted JSON:
+
+```bash
+curl -H "Authorization: Bearer <token>" "http://127.0.0.1:8787/api/snapshot?redact=1"
+```

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "logseq-graph-living-atlas",
+  "version": "0.1.0",
+  "description": "Local-only cinematic 3D atlas and read-only index service for Logseq markdown graphs.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "packageManager": "npm@10.8.2",
+  "keywords": [
+    "logseq",
+    "knowledge-graph",
+    "threejs",
+    "visualization",
+    "local-first"
+  ],
+  "homepage": "https://github.com/johnschieferleuhlenbrock/logseq-graph-living-atlas#readme",
+  "bugs": {
+    "url": "https://github.com/johnschieferleuhlenbrock/logseq-graph-living-atlas/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnschieferleuhlenbrock/logseq-graph-living-atlas.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "living-atlas": "server/brain-service.mjs",
+    "logseq-graph-living-atlas": "server/brain-service.mjs"
+  },
+  "files": [
+    "dist/",
+    "server/",
+    "docs/API.md",
+    "docs/ADAPTERS.md",
+    "docs/ARCHITECTURE.md",
+    "docs/CONCEPTS.md",
+    "docs/MCP.md",
+    "docs/RELEASE.md",
+    "docs/REPO_GUIDE.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/assets/living-atlas-demo.png",
+    "docs/assets/living-atlas-pathfinder.png",
+    "docs/assets/living-atlas-radar.png",
+    "docs/assets/living-atlas-source-detail.png",
+    "README.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "MAINTAINERS.md",
+    "GOVERNANCE.md",
+    "ROADMAP.md",
+    ".env.example",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5177",
+    "dev:api": "node server/brain-service.mjs --watch --no-static --port 8787",
+    "build": "vite build",
+    "start": "npm run demo",
+    "serve": "node server/brain-service.mjs --watch --static dist --port 8787",
+    "serve:env": "npm run build && node --env-file=.env.local server/brain-service.mjs --watch --static dist --port 8787",
+    "demo": "npm run build && node scripts/demo.mjs",
+    "dev:fixture": "node scripts/dev-fixture.mjs",
+    "capture:demo": "npm run build && node scripts/capture-demo.mjs",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "check:runtime": "node scripts/runtime-check.mjs",
+    "test": "node --test tests/*.test.mjs && npm run test:frontend && npm run typecheck && npm run check:runtime && npm run build",
+    "test:frontend": "tsx --test tests/frontend/*.test.ts",
+    "test:ui": "npm run build && node tests/ui-smoke.mjs",
+    "test:ui:scale": "npm run build && node tests/ui-scale-smoke.mjs",
+    "eval": "node tests/scale-eval.mjs && node tests/service-scale-eval.mjs",
+    "eval:service:100k": "node tests/service-scale-eval.mjs --size=100000 --watch",
+    "smoke:mcp": "node scripts/mcp-compat-smoke.mjs",
+    "smoke:package": "node scripts/package-smoke.mjs",
+    "check:public": "node scripts/public-readiness.mjs",
+    "check:release": "node scripts/release-readiness.mjs",
+    "clean": "node scripts/clean.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check:release && npm run validate && npm run smoke:package",
+    "validate": "npm test && npm run eval && npm run test:ui && npm run test:ui:scale && npm run check:public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.181.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "playwright": "^1.60.0",
+    "pngjs": "^7.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "three": "^0.181.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.4"
+  }
+}

package/server/brain-service.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_LOGSEQ_ROOT } from "./logseq/source-adapter.mjs";
+import { createBrainService } from "./service.mjs";
+import { createFixtureGraph } from "./fixture/create-fixture-graph.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf8"));
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main(process.argv.slice(2));
+}
+
+export async function main(argv = []) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+  if (args.version) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  const port = Number(args.port || process.env.LIVING_ATLAS_PORT || process.env.BRAIN_ATLAS_PORT || 8787);
+  const demoMode = Boolean(args.demo);
+  const rootInput = demoMode
+    ? createDemoGraphRoot()
+    : args.root || process.env.LOGSEQ_ROOT || DEFAULT_LOGSEQ_ROOT;
+  if (!rootInput) {
+    console.error("[living-atlas] LOGSEQ_ROOT or --root is required. Point it at a Logseq graph folder containing pages/.");
+    console.error("[living-atlas] Example: npx logseq-graph-living-atlas --root /path/to/logseq");
+    console.error("[living-atlas] Or try a public fixture: npx logseq-graph-living-atlas --demo");
+    console.error("[living-atlas] Run living-atlas --help for options.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const root = path.resolve(rootInput);
+  const packagedStaticDir = path.resolve(__dirname, "..", "dist");
+  const staticDir = args["no-static"]
+    ? null
+    : args.static
+      ? path.resolve(__dirname, "..", args.static)
+      : fs.existsSync(path.join(packagedStaticDir, "index.html"))
+        ? packagedStaticDir
+        : null;
+  const cachePath = path.resolve(args.cache || process.env.LIVING_ATLAS_CACHE || process.env.BRAIN_ATLAS_CACHE || path.join(defaultCacheDirectory(), "snapshot.json"));
+  const debugPaths = Boolean(args["debug-paths"] || process.env.LIVING_ATLAS_DEBUG_PATHS === "1" || process.env.BRAIN_ATLAS_DEBUG_PATHS === "1");
+  const allowUnauthenticatedRead = Boolean(args["allow-unauthenticated-read"] || process.env.LIVING_ATLAS_ALLOW_UNAUTHENTICATED_READ === "1");
+  const configuredToken = args.token || process.env.LIVING_ATLAS_TOKEN || process.env.BRAIN_ATLAS_TOKEN || "";
+  const requireToken = Boolean(
+    args["require-token"] ||
+    process.env.LIVING_ATLAS_REQUIRE_TOKEN === "1" ||
+    (!demoMode && !allowUnauthenticatedRead)
+  );
+  if (requireToken && configuredToken && configuredToken.length < 16) {
+    console.error("[living-atlas] LIVING_ATLAS_TOKEN / --token must be at least 16 characters when read-token mode is enabled.");
+    process.exitCode = 1;
+    return;
+  }
+  const localToken = requireToken ? configuredToken || crypto.randomBytes(18).toString("base64url") : configuredToken;
+
+  let service;
+  try {
+    service = createBrainService({
+      root,
+      cachePath,
+      staticDir,
+      port,
+      watch: Boolean(args.watch),
+      debugPaths,
+      token: localToken,
+      requireToken,
+      allowUnauthenticatedRead: demoMode || allowUnauthenticatedRead,
+      allowUnauthenticatedReindex: Boolean(args["allow-unauthenticated-reindex"] || process.env.LIVING_ATLAS_ALLOW_UNAUTHENTICATED_REINDEX === "1"),
+      allowedOrigins: args["allowed-origin"] || process.env.LIVING_ATLAS_ALLOWED_ORIGINS || process.env.BRAIN_ATLAS_ALLOWED_ORIGINS || ""
+    });
+    const started = await service.listen();
+    console.log(`[living-atlas] root = ${debugPaths ? root : "configured Logseq graph"}`);
+    if (demoMode) console.log("[living-atlas] demo = public fixture graph");
+    console.log(`[living-atlas] snapshot = ${started.snapshot.totals.nodes} nodes / ${started.snapshot.totals.links} links`);
+    console.log(`[living-atlas] api = http://${started.bindHost}:${started.port}/api/snapshot`);
+    if (requireToken) {
+      const appPort = staticDir ? started.port : 5177;
+      console.log(`[living-atlas] token-protected reads = enabled`);
+      if (!configuredToken) console.log(`[living-atlas] session token = ${localToken}`);
+      console.log(`[living-atlas] app token URL = http://${started.bindHost}:${appPort}/#token=${encodeURIComponent(localToken)}`);
+    }
+    if (staticDir) console.log(`[living-atlas] app = http://${started.bindHost}:${started.port}/`);
+  } catch (error) {
+    failStartup(error, debugPaths);
+    return;
+  }
+
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, async () => {
+      await service.close();
+      process.exit(0);
+    });
+  }
+}
+
+export function defaultCacheDirectory() {
+  if (process.env.XDG_CACHE_HOME) return path.join(process.env.XDG_CACHE_HOME, "logseq-graph-living-atlas");
+  if (process.platform === "darwin") return path.join(os.homedir(), "Library", "Caches", "logseq-graph-living-atlas");
+  if (process.platform === "win32") {
+    return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "logseq-graph-living-atlas");
+  }
+  return path.join(os.homedir(), ".cache", "logseq-graph-living-atlas");
+}
+
+function createDemoGraphRoot() {
+  const cacheDirectory = defaultCacheDirectory();
+  fs.mkdirSync(cacheDirectory, { recursive: true });
+  return createFixtureGraph({ out: fs.mkdtempSync(path.join(cacheDirectory, "demo-logseq-graph-")) });
+}
+
+function failStartup(error, debugPaths) {
+  const message = String(error?.message || error || "Startup failed");
+  console.error(`[living-atlas] ${message}`);
+  console.error("[living-atlas] Expected --root to point at a Logseq graph folder containing pages/.");
+  console.error("[living-atlas] Try: living-atlas --root /path/to/logseq");
+  console.error("[living-atlas] Or run the public fixture: living-atlas --demo");
+  if (debugPaths) console.error(error?.stack || error);
+  process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+  const parsed = {};
+  const valueFlags = new Set(["root", "cache", "port", "static", "token", "allowed-origin"]);
+  const booleanFlags = new Set([
+    "watch",
+    "help",
+    "version",
+    "debug-paths",
+    "no-static",
+    "demo",
+    "require-token",
+    "allow-unauthenticated-read",
+    "allow-unauthenticated-reindex"
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) continue;
+    const inline = arg.match(/^--([^=]+)=(.*)$/);
+    if (inline) {
+      parsed[inline[1]] = inline[2];
+      continue;
+    }
+    const key = arg.slice(2);
+    if (booleanFlags.has(key)) {
+      parsed[key] = true;
+      continue;
+    }
+    if (valueFlags.has(key)) {
+      parsed[key] = argv[index + 1];
+      index += 1;
+    }
+  }
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Living Atlas ${packageJson.version}
+
+Usage:
+  living-atlas --root /path/to/logseq [options]
+  npx logseq-graph-living-atlas --root /path/to/logseq
+  npx logseq-graph-living-atlas --demo
+
+Options:
+  --root <path>             Logseq graph folder containing pages/. journals/ is optional.
+  --demo                    Run a public fixture graph without needing Logseq data.
+  --port <number>           Local port. Defaults to 8787.
+  --cache <path>            Snapshot cache path outside the graph.
+  --static <path>           Static UI directory. Defaults to packaged dist/ when present.
+  --no-static               Serve API only.
+  --watch                   Watch pages/ and journals/ for markdown changes.
+  --token <value>           Local API token. Required for reads when token mode is enabled.
+  --require-token           Require the token for every /api/* read and write route.
+  --allow-unauthenticated-read
+                            Allow local API reads without a token for trusted development.
+  --allow-unauthenticated-reindex
+                            Allow POST /api/reindex without a token for local development.
+  --allowed-origin <origin> Add a local browser origin for split dev CORS.
+  --debug-paths             Include absolute diagnostic paths and detailed errors.
+  --version                 Print version.
+  --help                    Print this help.
+
+Examples:
+  npx logseq-graph-living-atlas --demo
+  npx logseq-graph-living-atlas --root ~/Documents/Logseq
+  living-atlas --root ~/Documents/Logseq --port 8787 --watch
+  LIVING_ATLAS_TOKEN=<random-local-token> LIVING_ATLAS_ALLOWED_ORIGINS=http://127.0.0.1:5177 npm run dev:api -- --root ~/Documents/Logseq
+`);
+}