llmwiki-bridge-start 0.0.1

package/LICENSE

@@ -0,0 +1,13 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+

package/README.md

@@ -0,0 +1,235 @@
+# llmwiki-bridge-start
+
+Local adoption harness for connecting pre-built LLMWiki/OpenWiki knowledge
+artifacts to `llmwiki-serve`, `llmwiki-agent-bridge`, and coding-agent clients.
+
+This package does not compile or ingest knowledge. It discovers existing wiki
+folders and Markdown knowledge-tool roots, validates that `llmwiki-serve` can
+read them, starts loopback source servers when requested, registers those
+sources with a local bridge when requested, and runs bridge smoke checks.
+
+## Quick Start
+
+Recommended first run:
+
+```bash
+npx llmwiki-bridge-start@latest --path ./wiki
+npx llmwiki-bridge-start@latest --workspace
+npx llmwiki-bridge-start@latest
+```
+
+Use `--path ./wiki` when you already know the source folder. The scan is
+constrained to that directory tree, so quickstart does not wander into your
+home directory, workspace siblings, or unrelated local projects. Use
+`--workspace` when you want quickstart to look under your `~/workspace`
+directory. Use
+the bare command when you want the guided flow to propose a broader scan; it
+asks before scanning the current user's home directory.
+
+Minimum success: when quickstart starts `llmwiki-serve` and reports healthy
+loopback source endpoints, first onboarding has succeeded. If you skip
+`llmwiki-agent-bridge`, quickstart prints one MCP Streamable HTTP registration
+URL per started source, using the `http://127.0.0.1:<port>/mcp/stream` shape.
+These are MCP-over-HTTP/Streamable HTTP server URLs for coding agents or
+scripts that support MCP over HTTP; exact client configuration syntax varies by
+client. `llmwiki-agent-bridge` can still be added later when you want source
+fan-out or one normalized bridge across sources.
+
+If `llmwiki-serve` is not on `PATH`, a sibling `../llmwiki-serve` checkout with
+an existing `.venv` is used automatically when available. Otherwise point the
+harness at a local checkout or environment explicitly, for example:
+
+```bash
+npx llmwiki-bridge-start@latest --path ./wiki \
+  --serve-command uv --serve-arg run --serve-arg llmwiki-serve --serve-cwd ../llmwiki-serve
+```
+
+Running `npx llmwiki-bridge-start@latest` with no subcommand starts the bounded
+first-run quickstart flow; `quickstart` remains an explicit equivalent. By
+default it asks before scanning the current user's home directory. Use `--path
+DIR`, `--workspace`, or `--cwd` to constrain discovery before answering yes.
+The flow shows a checkbox multi-select in interactive terminals, falls back to
+comma-separated numbered selection for piped/non-interactive runs, validates
+selected folders only when you choose to start them, waits for started
+loopback source URLs to answer health checks, then explains that those URLs can
+be used directly without
+`llmwiki-agent-bridge`. Bridge setup is optional: if you skip it, quickstart
+prints one coding-agent MCP Streamable HTTP registration URL (`/mcp/stream`)
+per started source. For simple local use, this `llmwiki-serve` direct path is
+already enough when your coding agent can register one or more MCP source URLs.
+Add `llmwiki-agent-bridge` only when you want one bridge endpoint across
+multiple sources or runtime-backed answers. Quickstart keeps the final screen
+concise with an operational details file reference. PIDs, log paths, and stop
+guidance are written to
+`.llmwiki-bridge-start/quickstart-handoff.md`. After you choose source folders,
+quickstart echoes the selected label and full path before validation/start. If
+stdin and stdout are both interactive TTYs, quickstart clears only the visible
+screen between major screens and redraws a compact `KBL / Knowledge Bridge
+Labs` logo block at the top of each focused screen; redirected/piped
+transcripts are unchanged. Use `--no-clear-screen` or
+`LLMWIKI_BRIDGE_START_NO_CLEAR_SCREEN=1` to keep all interactive screens
+visible. If
+you opt in, quickstart uses an already running bridge or prints copy-pasteable
+PowerShell and POSIX manual-start examples such as
+`LLMWIKI_AGENT_BRIDGE_HOST='127.0.0.1' LLMWIKI_AGENT_BRIDGE_PORT='8788' npx --yes llmwiki-agent-bridge@0.2.0`;
+custom `--bridge http://host:port` values are reflected in those env
+assignments. The command does not install a global package.
+Before starting that bridge command, quickstart asks how to configure the LLM
+runtime for this bridge run: skip/evidence-only, Hermes, or DeepAgents. In
+interactive terminals this is a single-select menu; piped/non-interactive runs
+keep numeric text input for scripting compatibility. Hermes and DeepAgents are
+the supported QuickStart runtime profiles. If the selected runtime CLI is
+missing and an official OS-specific installer is recorded here, interactive
+quickstart shows the exact documented install command, downloads the official
+HTTPS installer script to `.llmwiki-bridge-start/logs`, and runs it only after
+explicit approval. `--yes` automation still does not run runtime installers
+unless `--install-runtime` is also passed; use `--no-install-runtime` to suppress
+the installer prompt. Installation success only means the CLI was installed:
+Hermes still needs its own setup/API-server configuration and `hermes gateway`;
+DeepAgents still needs its own provider/auth setup. Runtime setup checks
+installed frameworks through their supported CLI entrypoints (`hermes --version`,
+`dcode --version`) and uses Hermes API server health (`/health` or `/v1/health`)
+when deciding whether a Hermes endpoint can be offered as the Enter default.
+DeepAgents Code is checked through `dcode`, but quickstart does not infer a
+bridge runtime endpoint from DeepAgents config because no supported local
+endpoint discovery contract is recorded here. Quickstart also does not treat
+legacy or user-local runtime aliases such as `HERMES_BASE_URL`,
+`DEEPAGENTS_BASE_URL`, or `OPENAI_BASE_URL` as first-run defaults. If a default
+endpoint is shown, it came from an explicit CLI flag, the standard
+`LLMWIKI_AGENT_BRIDGE_BASE_URL`, or a framework-supported local health probe
+such as Hermes `/health`; blank Enter uses that verified/configured default,
+and `skip` forces evidence-only. If no default endpoint is shown, blank Enter
+or `skip` continues with evidence-only bridge smoke.
+DeepAgents ACP is an explicit bridge adapter path, not the default DeepAgents
+profile behavior. Use `--runtime-adapter deepagents-acp` when you want
+QuickStart to configure `runtimeAdapter=deepagents-acp`; a background bridge
+start then receives `LLMWIKI_AGENT_BRIDGE_RUNTIME_ADAPTER=deepagents-acp`, and
+an already running bridge receives `runtimeAdapter: "deepagents-acp"` through
+`/settings/config.json`. Without that explicit adapter flag, DeepAgents keeps
+the existing endpoint-based compatibility path when you enter an
+OpenAI-compatible runtime URL, or the safe evidence-only fallback when you do
+not. Inherited `LLMWIKI_AGENT_BRIDGE_RUNTIME_ADAPTER` values in the parent
+shell are ignored by QuickStart and scrubbed before background bridge startup;
+use the explicit flag when ACP is intended.
+Quickstart runs the bridge start command only after a second explicit
+approval. Once a bridge is running, it merge-registers the started sources and
+runs an A2A-style smoke request. After a successful bridge smoke, quickstart
+prints a concise bridge handoff with the bridge base URL, A2A-style answer
+endpoint (`POST /message:send`), MCP-style JSON-RPC endpoint (`POST /mcp`),
+settings UI (`/settings`), and a compact operational details section that
+points to `.llmwiki-bridge-start/quickstart-handoff.md` for PIDs, log paths,
+and stop guidance. The bridge endpoint handoff is separate from direct source
+MCP Streamable HTTP URLs (`/mcp/stream`). If an explicit LLM
+endpoint is configured through flags, quickstart treats it as a preconfigured
+compatibility path without adding it to the interactive first-run menu.
+
+Quickstart keeps the first selection list focused. By default it shows
+recommended LLMWiki source folders: Native LLMWiki/OpenWiki projections and
+LLMWiki Markdown roots. Native LLMWiki/OpenWiki means an already compiled
+projection; LLMWiki Markdown means a source-like wiki that can be served
+through the Markdown adapter. App vaults, graphs, workspaces, generic Markdown
+folders, and noisy example/demo/starter/e2e paths are treated as
+advanced/lower-priority candidates. They are hidden from the default
+quickstart selection list when at least one recommended source exists. Use
+`--include-additional` to render recommended and advanced/lower-priority
+candidates as separate selectable sections.
+If an app vault contains a strong direct child `wiki/` source, default
+quickstart presents the child as recommended and keeps the parent app vault in
+the advanced/lower-priority section. If quickstart finds only
+advanced/lower-priority candidates without `--include-additional`, it stops
+before selection and asks you to rerun with `--include-additional`.
+
+The scriptable `discover` command is inventory, not presentation. Within the
+directories it scans, it reports every candidate that meets its score threshold,
+including parent/child overlaps and app vault roots that also contain a strong
+child `wiki/` source. Noisy-path and advanced/lower-priority filtering is a
+quickstart UX policy, not a broad-discover hiding rule.
+
+`--yes` is intended for local smoke automation: it accepts discovery and source
+startup defaults, selects the first candidate, and still skips optional bridge
+setup unless `--setup-bridge` is also supplied.
+
+Default discovery scans the user home directory unless `--path`, `--cwd`, or
+`--workspace` is supplied. The scanner prefers optional local tools such as
+`fd`/`rg` when available and falls back to Node traversal. It scores likely
+wiki roots, exposes the markers behind each score, keeps parent/child overlap
+visible when both paths meet the score threshold, and optionally validates
+candidates with `llmwiki-serve manifest`. The default minimum score is `30`.
+Generic Markdown folders are often low confidence, so use `--min-score 10` when
+intentionally looking for plain Markdown folders. Broad scans still avoid
+dependency, cache, build, transient editor/download, and other infrastructure
+folders; pass an explicit `--path DIR` when you intentionally want to inspect a
+normally skipped area.
+
+Quickstart intentionally prints full local paths for disambiguation so users can
+distinguish candidate folders before starting servers. Redact or replace those
+paths and any private bridge/runtime endpoints before publishing screenshots,
+logs, docs, or issue reports.
+When several visible candidates are all named `wiki`, or a candidate is under
+`.llmwiki-work`, quickstart adds a small parent/project context to the display
+label while still printing the full path on the next line.
+
+### Advanced/scriptable commands
+
+Use these when you want to automate or debug individual steps. They are not a
+required first-run sequence.
+
+```bash
+npx llmwiki-bridge-start@latest discover --home
+npx llmwiki-bridge-start@latest discover --path . --validate
+npx llmwiki-bridge-start@latest start --path ./wiki --port 11001
+npx llmwiki-bridge-start@latest register --bridge http://127.0.0.1:8788 --config .llmwiki-bridge-start/sources.json
+npx llmwiki-bridge-start@latest smoke --bridge http://127.0.0.1:8788
+```
+
+## Supported Source Variants
+
+`discover` is a heuristic finder. The score and confidence explain why a folder
+looks like a candidate; `--validate` is the compatibility check that asks
+`llmwiki-serve manifest` whether the candidate can actually be served.
+
+| Variant | Meaning | Detection markers | Default confidence |
+| --- | --- | --- | --- |
+| Native LLMWiki/OpenWiki projection | An already-built projection intended to be served by `llmwiki-serve`. | `.wiki-compiler.json`; sidecar graph or projection metadata such as `graph/graph.json`; or structural projection combinations that include stronger projection frontmatter such as `source_refs` or `sources`, `hot.md` plus `index.md` or `overview.md`, and typed folders such as `concepts/`, `entities/`, `sources/`, or `queries/`. Frontmatter alone, `review_state` alone, `wiki_title` alone, `hot.md` alone, and docs-like hub plus typed folders are not enough to classify Native. | Usually medium to high; high when multiple projection markers are present. |
+| LLMWiki Markdown | A source-like Markdown wiki root that `llmwiki-serve` can often read with its Markdown adapter, but that is not a compiled Native projection. | Source-like root names such as `wiki`, `llmwiki`, `openwiki`, or `vault`, plus typed folders and either a strong hub pair (`hot.md` plus `index.md`/`overview.md`) or a hub file with a larger Markdown set. | Usually medium to high; validate before treating it as startable. |
+| Obsidian vault | A plain-file Obsidian vault that may be usable directly or through a future adapter. | `.obsidian/` plus Markdown notes. If the vault has a strong direct child `wiki/` source, `discover` keeps both the vault root and child visible when both meet the score threshold. Default quickstart presents the child as recommended and the parent app vault as advanced/lower-priority. App markers keep the app variant label unless stronger projection evidence such as `.wiki-compiler.json`, sidecar graph metadata, or `source_refs` marks a compiled projection. | Medium before validation; higher only if projection markers are also present. |
+| Logseq graph | A Logseq knowledge graph. | `logseq/config.edn`, or the weaker fallback of both `pages/` and `journals/`. | Medium for `logseq/config.edn`; low for `pages/` plus `journals/` unless other source-like hints are present. |
+| Dendron workspace | A Dendron workspace or vault root. | `dendron.yml`. | Medium. |
+| Foam workspace | A Foam Markdown workspace. | `.foam/`, or the weaker fallback of a VS Code extensions recommendation that mentions Foam. | Medium for `.foam/`; low for the VS Code hint unless other source-like hints are present. |
+| Quartz site source | A Quartz site content repository. | `quartz.config.ts`, `.js`, `.yaml`, or `.yml`. | Medium. |
+| Generic Markdown fallback | A folder of Markdown or Org files without a known app or projection marker. | Markdown file counts, source-like folder names such as `wiki`, `llmwiki`, `openwiki`, or `vault`, hub files, and projection-like frontmatter. | Low by default and capped below the default `--min-score 30`; use `--min-score 10` for intentional fallback discovery. |
+
+Confidence bands are score-based: `60+` is high, `30-59` is medium, `10-29` is
+low, and lower scores are hidden. Validation does not change the source files;
+it runs `llmwiki-serve manifest <candidate>` and reports `startable: yes/no`
+plus manifest fields such as title, source id, adapter, page counts, and graph
+counts when available. The `start` command performs the same manifest check
+before launching `llmwiki-serve serve`.
+
+See [Supported Source Variants](docs/supported-source-variants.md) for the
+longer compatibility notes and non-goals.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| no subcommand / `quickstart` | Guided first-run flow: optional discover, multi-select, validate/start sources, optional bridge setup, register, and A2A-style smoke. |
+| `discover` | Find local LLMWiki Markdown, Native LLMWiki/OpenWiki, Obsidian, Logseq, Foam, Dendron, Quartz, and generic Markdown candidates. |
+| `start` | Start `llmwiki-serve` on one or more selected local wiki paths. |
+| `register` | Upsert started or existing source URLs into `llmwiki-agent-bridge`. Use `--replace` only when intentionally replacing the registry. |
+| `smoke` | Run a bridge smoke request; defaults to evidence-only and accepts delegated-runtime or hybrid with `--mode`. |
+| `doctor` | Check local prerequisites and optional bridge reachability. |
+
+## Boundary
+
+`llmwiki-bridge-start` is an onboarding/adoption harness. It is not a wiki
+compiler, crawler, sync engine, model runtime, Redis manager, production auth
+layer, or replacement for `llmwiki-agent-bridge`. It also does not promise
+lossless interpretation of Obsidian, Logseq, Dendron, Foam, or Quartz-specific
+syntax; manifest validation is the source of truth for whether the current
+`llmwiki-serve` can serve a candidate.
+
+`llmwiki-agent-bridge` remains optional. Use the direct `llmwiki-serve`
+handoff URLs when your local agent or script can call each source itself. Add
+the bridge later when you want source fan-out, runtime-backed synthesis, or one
+normalized bridge across sources.

package/bin/llmwiki-bridge-start.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/index.mjs'
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error && typeof error.message === 'string' ? error.message : String(error)
+  console.error(`llmwiki-bridge-start: ${message}`)
+  process.exitCode = 1
+})
+

package/docs/supported-source-variants.md

@@ -0,0 +1,75 @@
+# Supported Source Variants
+
+`llmwiki-bridge-start discover` is a heuristic finder. It does not certify that
+a folder is usable. The compatibility check is `llmwiki-serve manifest`, which
+is run by `discover --validate`, `quickstart` after candidate selection, and
+`start` before launching a source server.
+
+`discover` is scriptable inventory. Within the directories it scans, it should
+show every candidate that meets the selected score threshold, including
+parent/child overlap and app vault roots that also contain a strong child
+`wiki/` source. `quickstart` is the presentation layer: by default it
+recommends Native LLMWiki/OpenWiki and LLMWiki Markdown sources. Native
+LLMWiki/OpenWiki means an already compiled projection; LLMWiki Markdown means a
+source-like wiki served through the Markdown adapter. App vaults, graphs,
+workspaces, generic Markdown folders, and noisy example/demo/starter/e2e paths
+are advanced/lower-priority candidates and visible with `--include-additional`.
+
+For first-run onboarding, prefer `--path DIR` when you already know the source
+folder. That constrains discovery to the selected directory tree instead of
+scanning the current user's home directory or unrelated workspace siblings.
+
+## Variants
+
+| Variant | Intended use | Detection markers | Default confidence |
+| --- | --- | --- | --- |
+| Native LLMWiki/OpenWiki projection | Already-built source projection for serving to coding agents. | `.wiki-compiler.json`; sidecar graph or projection metadata such as `graph/graph.json`; or structural projection combinations that include stronger projection frontmatter such as `source_refs` or `sources`, `hot.md` plus `index.md` or `overview.md`, and typed folders such as `concepts/`, `entities/`, `sources/`, or `queries/`. Frontmatter alone, `review_state` alone, `wiki_title` alone, `hot.md` alone, and docs-like hub plus typed folders are not enough to classify Native. | Usually medium to high; high when several projection markers combine. |
+| LLMWiki Markdown | Source-like Markdown wiki root for `llmwiki-serve`'s Markdown adapter. | Source-like root names such as `wiki`, `llmwiki`, `openwiki`, or `vault`, plus typed folders and either a strong hub pair (`hot.md` plus `index.md`/`overview.md`) or a hub file with a larger Markdown set. | Usually medium to high; validate before treating it as startable. |
+| Obsidian vault | Plain-file Obsidian vault that may include a nested `wiki/` hub. | `.obsidian/` plus Markdown notes. Strong direct child `wiki/` sources do not remove the vault root from `discover`; both are listed when both meet the score threshold. Default quickstart recommends the child `wiki/` source and places the parent app vault in the advanced/lower-priority section. App markers keep the app variant label unless stronger projection evidence such as `.wiki-compiler.json`, sidecar graph metadata, or `source_refs` marks a compiled projection. | Medium before validation; higher only when projection markers are also present. |
+| Logseq graph | Local Logseq graph. | `logseq/config.edn`, or weaker fallback markers `pages/` plus `journals/`. | Medium for config; low for only `pages/` plus `journals/`. |
+| Dendron workspace | Dendron workspace or vault root. | `dendron.yml`. | Medium. |
+| Foam workspace | Foam Markdown workspace. | `.foam/`, or a VS Code extension recommendation mentioning Foam. | Medium. |
+| Quartz site source | Quartz source repository. | `quartz.config.ts`, `quartz.config.js`, `quartz.config.yaml`, or `quartz.config.yml`. | Medium. |
+| Generic Markdown fallback | Deliberately selected Markdown/Org folder without stronger app or projection markers. | Markdown/Org count, source-like root names such as `wiki`, `llmwiki`, `openwiki`, or `vault`, hub files, and projection-like frontmatter. | Low by default and capped below `--min-score 30`; use `--min-score 10` intentionally. |
+
+## Confidence and validation
+
+- `60+`: high confidence.
+- `30-59`: medium confidence.
+- `10-29`: low confidence.
+- Below `10`: hidden.
+
+Confidence is only a discovery score. Validation is separate:
+
+```bash
+llmwiki-bridge-start discover --path . --validate
+```
+
+Validation reports whether the candidate is `startable` and includes manifest
+fields such as title, source id, adapter, page counts, approved page counts, and
+graph counts when available.
+
+## Discovery transparency and quickstart filtering
+
+Broad `discover` output is threshold-driven inventory after traversal safety
+guards have selected directories to inspect. It must not hide otherwise scoring
+candidates merely because they are app vault roots, generic Markdown folders,
+or parents of stronger child `wiki/` sources. Quickstart applies the default UX
+filter by splitting candidates into recommended and advanced/lower-priority
+sections; pass `--include-additional` to make the advanced section selectable.
+
+Traversal may still avoid infrastructure folders that are not useful source
+roots, such as dependency, cache, build, transient editor/download, and OS
+folders. That safety guard is separate from noisy-path presentation filtering.
+When `--path DIR` is supplied, traversal is constrained to that directory tree;
+use it for targeted validation and for normally skipped areas that you
+intentionally want to inspect.
+
+The CLI prints full local paths for disambiguation by design. Redact or replace
+those paths before publishing screenshots, logs, docs, or issue reports.
+
+## Non-goals
+
+This package does not compile repositories into knowledge graphs, convert
+app-specific syntax into canonical LLMWiki pages, crawl remote wikis, sync app
+state, manage Redis or model runtimes, or replace `llmwiki-agent-bridge`.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "llmwiki-bridge-start",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "description": "Local adoption harness for connecting pre-built LLMWiki knowledge sources to agent bridges and coding-agent clients.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowledge-bridge-labs/llmwiki-bridge-start.git"
+  },
+  "bugs": {
+    "url": "https://github.com/knowledge-bridge-labs/llmwiki-bridge-start/issues"
+  },
+  "homepage": "https://knowledge-bridge-labs.github.io/llmwiki-docs/",
+  "keywords": [
+    "llmwiki",
+    "knowledge-source",
+    "agent-runtime",
+    "mcp",
+    "a2a",
+    "onboarding",
+    "bridge",
+    "codex",
+    "claude-code",
+    "cursor"
+  ],
+  "main": "./src/index.mjs",
+  "exports": "./src/index.mjs",
+  "bin": {
+    "llmwiki-bridge-start": "bin/llmwiki-bridge-start.mjs"
+  },
+  "files": [
+    "bin/llmwiki-bridge-start.mjs",
+    "docs/supported-source-variants.md",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "npm@10.9.7",
+  "engines": {
+    "node": ">=22.12",
+    "npm": ">=10"
+  },
+  "scripts": {
+    "lint": "node --check bin/llmwiki-bridge-start.mjs && node --check src/index.mjs && node --check test/discover.test.mjs",
+    "test": "node --test test/*.test.mjs",
+    "check": "npm run lint && npm test && npm run pack:dry-run",
+    "pack:dry-run": "npm pack --dry-run --json --ignore-scripts",
+    "audit": "npm audit --omit=dev"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.7.0",
+    "cross-spawn": "^7.0.6",
+    "sisteransi": "^1.0.5"
+  }
+}