org-wiki 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
org_wiki-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kenan Sharifli
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,203 @@
1
+ Metadata-Version: 2.4
2
+ Name: org-wiki
3
+ Version: 0.1.0
4
+ Summary: Turn any GitHub org into a self-updating engineering wiki with offline hybrid semantic search, Web UI, and MCP server.
5
+ Author: Kenan Sharifli
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/sharifli4/org-wiki
8
+ Project-URL: Repository, https://github.com/sharifli4/org-wiki
9
+ Project-URL: Issues, https://github.com/sharifli4/org-wiki/issues
10
+ Keywords: wiki,knowledge-base,github,mcp,semantic-search,bm25,rag,developer-tools
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Environment :: Web Environment
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Software Development :: Documentation
22
+ Requires-Python: >=3.10
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: fastembed>=0.3.6
26
+ Requires-Dist: numpy>=1.26.0
27
+ Dynamic: license-file
28
+
29
+ # org-wiki
30
+
31
+ Turn a GitHub organization into a searchable engineering wiki that updates itself when pull requests merge.
32
+
33
+ Point `org-wiki` at your GitHub org using your existing `gh auth` login. It reads your repositories, builds a plain-Markdown wiki of your APIs, database tables, queues, CI runners, and env var names, indexes everything locally on your machine, and serves a Web UI plus an MCP server for Cursor and Claude Code.
34
+
35
+ No SaaS account. No cloud vector database. Secret values are never copied.
36
+
37
+ ## What you need
38
+
39
+ - Python 3.10 or newer (`uv` or `pipx` recommended, plain `python3` works too)
40
+ - `git`
41
+ - `gh` (GitHub CLI, logged in with `gh auth login`) — or a `GH_TOKEN` environment variable
42
+
43
+ ## Install
44
+
45
+ Run instantly without installing via `uvx`:
46
+
47
+ ```bash
48
+ uvx org-wiki
49
+ ```
50
+
51
+ Or install globally (`org-wiki` and `orgwiki` commands):
52
+
53
+ ```bash
54
+ uv tool install org-wiki
55
+ ```
56
+
57
+ ```bash
58
+ pipx install org-wiki
59
+ ```
60
+
61
+ ```bash
62
+ pip install org-wiki
63
+ ```
64
+
65
+ One-line shell installer (auto-detects `uv`, `pipx`, or isolated `~/.local` venv):
66
+
67
+ ```bash
68
+ curl -fsSL https://raw.githubusercontent.com/sharifli4/org-wiki/main/install.sh | bash
69
+ ```
70
+
71
+ ## Quickstart (Browser Easy Mode)
72
+
73
+ Create an empty folder for your company's wiki and run `org-wiki` (or `orgwiki`):
74
+
75
+ ```bash
76
+ mkdir acme-wiki && cd acme-wiki
77
+ org-wiki
78
+ ```
79
+
80
+ Open `http://127.0.0.1:8787`.
81
+
82
+ 1. `org-wiki` detects your `gh auth` session and lists every GitHub organization (and personal account) you belong to.
83
+ 2. Pick your organization and check the repositories you want tracked.
84
+ 3. Click **Build & Index Wiki**.
85
+
86
+ `org-wiki` shallow-clones default branches into a temporary folder, writes the Markdown catalogs, builds a local SQLite + ONNX semantic index, and opens the search and Q&A screen.
87
+
88
+ ## Quickstart (Terminal Mode)
89
+
90
+ If you prefer the command line over the browser wizard:
91
+
92
+ ```bash
93
+ mkdir acme-wiki && cd acme-wiki
94
+ org-wiki init --org your-github-org
95
+ ```
96
+
97
+ Then search or ask questions offline:
98
+
99
+ ```bash
100
+ org-wiki search "billing_invoices"
101
+ org-wiki ask "Which service publishes invoice events and which table stores them?"
102
+ ```
103
+
104
+ ## Single-Box Docker Mode
105
+
106
+ Run the whole app inside one container (includes `git`, `gh`, and the pre-downloaded ONNX embedding model):
107
+
108
+ ```bash
109
+ git clone https://github.com/sharifli4/org-wiki.git
110
+ cd org-wiki
111
+ GH_TOKEN="$(gh auth token)" docker compose up -d
112
+ ```
113
+
114
+ Open `http://127.0.0.1:8787`. Everything is stored in `./wiki-data`.
115
+
116
+ ## Connect Cursor & Claude Code (MCP)
117
+
118
+ Give your AI coding agent direct access to `wiki_search`, `wiki_ask`, `wiki_read_doc`, `wiki_list_docs`, and `wiki_sync`:
119
+
120
+ ```bash
121
+ org-wiki mcp --install cursor
122
+ org-wiki mcp --install claude-code
123
+ ```
124
+
125
+ Or click **Connect IDE (MCP)** in the top bar of the Web UI.
126
+
127
+ ## What gets created in your workspace
128
+
129
+ ```text
130
+ acme-wiki/
131
+ ├── org-wiki.toml # Tracked org, excluded repos, domain groupings
132
+ ├── INDEX.md # Entry table routing engineers & AI agents
133
+ ├── 00-infra-and-access/ # Servers, runners, dashboards, open questions
134
+ ├── 01-system-map/
135
+ │ ├── company-overview.md # Cross-repo topology map
136
+ │ └── repo-catalog.md # Auto-harvested active & archived GitHub repos
137
+ ├── 02-runbooks/ # Step-by-step operational guides
138
+ ├── 03-features/ # End-to-end feature mechanics
139
+ ├── 04-decisions/ # Architecture Decision Records (ADRs)
140
+ ├── 05-reference/ # Auto-harvested from code (never hand-edit)
141
+ │ ├── http-apis.md # NestJS, Express/Fastify, Next.js, FastAPI/Flask/Django, Go, Spring
142
+ │ ├── data-models.md # Prisma, TypeORM/MikroORM/Sequelize, SQLAlchemy/Django, GORM, SQL
143
+ │ ├── messaging-and-queues.md # Exchanges, queues, topics, cross-repo mismatches
144
+ │ ├── ci-workflows.md # GitHub Actions workflows & runs-on labels
145
+ │ └── env-vars.md # Variable names from .env.example (values stripped)
146
+ └── .github/workflows/sync-wiki.yml # Keeps the repo updated automatically on GitHub
147
+ ```
148
+
149
+ ## How auto-sync works on GitHub
150
+
151
+ `org-wiki` uses a two-speed update model so factual catalogs never hallucinate and architecture prose stays reviewed by humans:
152
+
153
+ 1. **Publish the wiki repo** to your GitHub org:
154
+ ```bash
155
+ org-wiki publish-repo
156
+ ```
157
+ 2. **Add `WIKI_ORG_TOKEN`** on `<org>/<wiki-repo>` (read access to org repos + read/write contents and pull requests on `<wiki-repo>`), plus an org secret **`WIKI_DISPATCH_TOKEN`** scoped to `<wiki-repo>`.
158
+ 3. **Connect your product repositories** (dry-run first, then `--apply` to open onboarding PRs):
159
+ ```bash
160
+ org-wiki connect-repos
161
+ org-wiki connect-repos --apply
162
+ ```
163
+
164
+ Whenever a PR merges in a connected repository:
165
+ - **Job 1 (`harvest-to-main`)** deterministically re-harvests `05-reference/*` and `01-system-map/repo-catalog.md` from GitHub default branches and commits straight to `main`.
166
+ - **Job 2 (`draft-feature-pr`)** reads the merged PR diff and opens a human-reviewed PR on `<wiki-repo>` only when feature mechanics, runbooks, system maps, or ADRs changed.
167
+
168
+ ## Commands
169
+
170
+ Both `org-wiki` and `orgwiki` run the same CLI:
171
+
172
+ | Command | Description |
173
+ | --- | --- |
174
+ | `org-wiki` | Start Web UI on `http://127.0.0.1:8787` (setup wizard + search + Q&A + editor) |
175
+ | `org-wiki init --org <owner>` | Interactive or non-interactive workspace setup via `gh auth` |
176
+ | `org-wiki search "<query>"` | Offline hybrid search (ONNX `BAAI/bge-small-en-v1.5` + SQLite FTS5 BM25) |
177
+ | `org-wiki ask "<question>"` | Cited Q&A (synthesizes prose when an LLM is configured, offline hits otherwise) |
178
+ | `org-wiki harvest` | Re-harvest routes, tables, queues, workflows, and env var names from GitHub |
179
+ | `org-wiki sync` | Pull or re-harvest latest changes and incrementally update the local index |
180
+ | `org-wiki index [--force]` | Build or rebuild the local SQLite + ONNX index |
181
+ | `org-wiki mcp [--install cursor\|claude-code]` | Run stdio MCP server or register it in your editor |
182
+ | `org-wiki publish-repo [--public]` | Create `<org>/<wiki-repo>` on GitHub via `gh` and push |
183
+ | `org-wiki connect-repos [--apply]` | Open PRs across org repos installing merge webhooks & AI rules |
184
+ | `org-wiki doctor` | Check Python, `gh auth`, `git`, embedding cache, and LLM configuration |
185
+
186
+ ## Optional AI answer synthesis
187
+
188
+ Search and MCP retrieval run 100% offline with zero API keys. If you also want synthesized prose answers with inline `[path]` citations in `org-wiki ask`, the Web UI, and `wiki_ask`, set any one of these in `.env` or your shell:
189
+
190
+ - **Anthropic:** `ANTHROPIC_API_KEY=sk-ant-...`
191
+ - **OpenAI / compatible:** `OPENAI_API_KEY=sk-...` (optional `OPENAI_BASE_URL=...`)
192
+ - **Local Ollama:** `OLLAMA_MODEL=llama3.2` (optional `OLLAMA_HOST=http://127.0.0.1:11434`)
193
+ - **GitHub Models (reuses `gh auth`):** `ORGWIKI_USE_GH_MODELS=1`
194
+
195
+ ## Tests
196
+
197
+ ```bash
198
+ python3 -m unittest discover -s tests -v
199
+ ```
200
+
201
+ ## License
202
+
203
+ MIT
@@ -0,0 +1,175 @@
1
+ # org-wiki
2
+
3
+ Turn a GitHub organization into a searchable engineering wiki that updates itself when pull requests merge.
4
+
5
+ Point `org-wiki` at your GitHub org using your existing `gh auth` login. It reads your repositories, builds a plain-Markdown wiki of your APIs, database tables, queues, CI runners, and env var names, indexes everything locally on your machine, and serves a Web UI plus an MCP server for Cursor and Claude Code.
6
+
7
+ No SaaS account. No cloud vector database. Secret values are never copied.
8
+
9
+ ## What you need
10
+
11
+ - Python 3.10 or newer (`uv` or `pipx` recommended, plain `python3` works too)
12
+ - `git`
13
+ - `gh` (GitHub CLI, logged in with `gh auth login`) — or a `GH_TOKEN` environment variable
14
+
15
+ ## Install
16
+
17
+ Run instantly without installing via `uvx`:
18
+
19
+ ```bash
20
+ uvx org-wiki
21
+ ```
22
+
23
+ Or install globally (`org-wiki` and `orgwiki` commands):
24
+
25
+ ```bash
26
+ uv tool install org-wiki
27
+ ```
28
+
29
+ ```bash
30
+ pipx install org-wiki
31
+ ```
32
+
33
+ ```bash
34
+ pip install org-wiki
35
+ ```
36
+
37
+ One-line shell installer (auto-detects `uv`, `pipx`, or isolated `~/.local` venv):
38
+
39
+ ```bash
40
+ curl -fsSL https://raw.githubusercontent.com/sharifli4/org-wiki/main/install.sh | bash
41
+ ```
42
+
43
+ ## Quickstart (Browser Easy Mode)
44
+
45
+ Create an empty folder for your company's wiki and run `org-wiki` (or `orgwiki`):
46
+
47
+ ```bash
48
+ mkdir acme-wiki && cd acme-wiki
49
+ org-wiki
50
+ ```
51
+
52
+ Open `http://127.0.0.1:8787`.
53
+
54
+ 1. `org-wiki` detects your `gh auth` session and lists every GitHub organization (and personal account) you belong to.
55
+ 2. Pick your organization and check the repositories you want tracked.
56
+ 3. Click **Build & Index Wiki**.
57
+
58
+ `org-wiki` shallow-clones default branches into a temporary folder, writes the Markdown catalogs, builds a local SQLite + ONNX semantic index, and opens the search and Q&A screen.
59
+
60
+ ## Quickstart (Terminal Mode)
61
+
62
+ If you prefer the command line over the browser wizard:
63
+
64
+ ```bash
65
+ mkdir acme-wiki && cd acme-wiki
66
+ org-wiki init --org your-github-org
67
+ ```
68
+
69
+ Then search or ask questions offline:
70
+
71
+ ```bash
72
+ org-wiki search "billing_invoices"
73
+ org-wiki ask "Which service publishes invoice events and which table stores them?"
74
+ ```
75
+
76
+ ## Single-Box Docker Mode
77
+
78
+ Run the whole app inside one container (includes `git`, `gh`, and the pre-downloaded ONNX embedding model):
79
+
80
+ ```bash
81
+ git clone https://github.com/sharifli4/org-wiki.git
82
+ cd org-wiki
83
+ GH_TOKEN="$(gh auth token)" docker compose up -d
84
+ ```
85
+
86
+ Open `http://127.0.0.1:8787`. Everything is stored in `./wiki-data`.
87
+
88
+ ## Connect Cursor & Claude Code (MCP)
89
+
90
+ Give your AI coding agent direct access to `wiki_search`, `wiki_ask`, `wiki_read_doc`, `wiki_list_docs`, and `wiki_sync`:
91
+
92
+ ```bash
93
+ org-wiki mcp --install cursor
94
+ org-wiki mcp --install claude-code
95
+ ```
96
+
97
+ Or click **Connect IDE (MCP)** in the top bar of the Web UI.
98
+
99
+ ## What gets created in your workspace
100
+
101
+ ```text
102
+ acme-wiki/
103
+ ├── org-wiki.toml # Tracked org, excluded repos, domain groupings
104
+ ├── INDEX.md # Entry table routing engineers & AI agents
105
+ ├── 00-infra-and-access/ # Servers, runners, dashboards, open questions
106
+ ├── 01-system-map/
107
+ │ ├── company-overview.md # Cross-repo topology map
108
+ │ └── repo-catalog.md # Auto-harvested active & archived GitHub repos
109
+ ├── 02-runbooks/ # Step-by-step operational guides
110
+ ├── 03-features/ # End-to-end feature mechanics
111
+ ├── 04-decisions/ # Architecture Decision Records (ADRs)
112
+ ├── 05-reference/ # Auto-harvested from code (never hand-edit)
113
+ │ ├── http-apis.md # NestJS, Express/Fastify, Next.js, FastAPI/Flask/Django, Go, Spring
114
+ │ ├── data-models.md # Prisma, TypeORM/MikroORM/Sequelize, SQLAlchemy/Django, GORM, SQL
115
+ │ ├── messaging-and-queues.md # Exchanges, queues, topics, cross-repo mismatches
116
+ │ ├── ci-workflows.md # GitHub Actions workflows & runs-on labels
117
+ │ └── env-vars.md # Variable names from .env.example (values stripped)
118
+ └── .github/workflows/sync-wiki.yml # Keeps the repo updated automatically on GitHub
119
+ ```
120
+
121
+ ## How auto-sync works on GitHub
122
+
123
+ `org-wiki` uses a two-speed update model so factual catalogs never hallucinate and architecture prose stays reviewed by humans:
124
+
125
+ 1. **Publish the wiki repo** to your GitHub org:
126
+ ```bash
127
+ org-wiki publish-repo
128
+ ```
129
+ 2. **Add `WIKI_ORG_TOKEN`** on `<org>/<wiki-repo>` (read access to org repos + read/write contents and pull requests on `<wiki-repo>`), plus an org secret **`WIKI_DISPATCH_TOKEN`** scoped to `<wiki-repo>`.
130
+ 3. **Connect your product repositories** (dry-run first, then `--apply` to open onboarding PRs):
131
+ ```bash
132
+ org-wiki connect-repos
133
+ org-wiki connect-repos --apply
134
+ ```
135
+
136
+ Whenever a PR merges in a connected repository:
137
+ - **Job 1 (`harvest-to-main`)** deterministically re-harvests `05-reference/*` and `01-system-map/repo-catalog.md` from GitHub default branches and commits straight to `main`.
138
+ - **Job 2 (`draft-feature-pr`)** reads the merged PR diff and opens a human-reviewed PR on `<wiki-repo>` only when feature mechanics, runbooks, system maps, or ADRs changed.
139
+
140
+ ## Commands
141
+
142
+ Both `org-wiki` and `orgwiki` run the same CLI:
143
+
144
+ | Command | Description |
145
+ | --- | --- |
146
+ | `org-wiki` | Start Web UI on `http://127.0.0.1:8787` (setup wizard + search + Q&A + editor) |
147
+ | `org-wiki init --org <owner>` | Interactive or non-interactive workspace setup via `gh auth` |
148
+ | `org-wiki search "<query>"` | Offline hybrid search (ONNX `BAAI/bge-small-en-v1.5` + SQLite FTS5 BM25) |
149
+ | `org-wiki ask "<question>"` | Cited Q&A (synthesizes prose when an LLM is configured, offline hits otherwise) |
150
+ | `org-wiki harvest` | Re-harvest routes, tables, queues, workflows, and env var names from GitHub |
151
+ | `org-wiki sync` | Pull or re-harvest latest changes and incrementally update the local index |
152
+ | `org-wiki index [--force]` | Build or rebuild the local SQLite + ONNX index |
153
+ | `org-wiki mcp [--install cursor\|claude-code]` | Run stdio MCP server or register it in your editor |
154
+ | `org-wiki publish-repo [--public]` | Create `<org>/<wiki-repo>` on GitHub via `gh` and push |
155
+ | `org-wiki connect-repos [--apply]` | Open PRs across org repos installing merge webhooks & AI rules |
156
+ | `org-wiki doctor` | Check Python, `gh auth`, `git`, embedding cache, and LLM configuration |
157
+
158
+ ## Optional AI answer synthesis
159
+
160
+ Search and MCP retrieval run 100% offline with zero API keys. If you also want synthesized prose answers with inline `[path]` citations in `org-wiki ask`, the Web UI, and `wiki_ask`, set any one of these in `.env` or your shell:
161
+
162
+ - **Anthropic:** `ANTHROPIC_API_KEY=sk-ant-...`
163
+ - **OpenAI / compatible:** `OPENAI_API_KEY=sk-...` (optional `OPENAI_BASE_URL=...`)
164
+ - **Local Ollama:** `OLLAMA_MODEL=llama3.2` (optional `OLLAMA_HOST=http://127.0.0.1:11434`)
165
+ - **GitHub Models (reuses `gh auth`):** `ORGWIKI_USE_GH_MODELS=1`
166
+
167
+ ## Tests
168
+
169
+ ```bash
170
+ python3 -m unittest discover -s tests -v
171
+ ```
172
+
173
+ ## License
174
+
175
+ MIT
@@ -0,0 +1,57 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "org-wiki"
7
+ version = "0.1.0"
8
+ description = "Turn any GitHub org into a self-updating engineering wiki with offline hybrid semantic search, Web UI, and MCP server."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [
13
+ { name = "Kenan Sharifli" },
14
+ ]
15
+ requires-python = ">=3.10"
16
+ keywords = [
17
+ "wiki",
18
+ "knowledge-base",
19
+ "github",
20
+ "mcp",
21
+ "semantic-search",
22
+ "bm25",
23
+ "rag",
24
+ "developer-tools",
25
+ ]
26
+ classifiers = [
27
+ "Development Status :: 4 - Beta",
28
+ "Environment :: Console",
29
+ "Environment :: Web Environment",
30
+ "Intended Audience :: Developers",
31
+ "Operating System :: OS Independent",
32
+ "Programming Language :: Python :: 3",
33
+ "Programming Language :: Python :: 3.10",
34
+ "Programming Language :: Python :: 3.11",
35
+ "Programming Language :: Python :: 3.12",
36
+ "Programming Language :: Python :: 3.13",
37
+ "Topic :: Software Development :: Documentation",
38
+ ]
39
+ dependencies = [
40
+ "fastembed>=0.3.6",
41
+ "numpy>=1.26.0",
42
+ ]
43
+
44
+ [project.urls]
45
+ Homepage = "https://github.com/sharifli4/org-wiki"
46
+ Repository = "https://github.com/sharifli4/org-wiki"
47
+ Issues = "https://github.com/sharifli4/org-wiki/issues"
48
+
49
+ [project.scripts]
50
+ org-wiki = "org_wiki.cli:main"
51
+ orgwiki = "org_wiki.cli:main"
52
+
53
+ [tool.setuptools]
54
+ package-dir = {"" = "src"}
55
+
56
+ [tool.setuptools.packages.find]
57
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,40 @@
1
+ """org-wiki: Single-box, self-updating company engineering wiki."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from pathlib import Path
7
+
8
+ __version__ = "0.1.0"
9
+
10
+ CONFIG_FILENAME = "org-wiki.toml"
11
+
12
+
13
+ def _is_tool_source_repo(directory: Path) -> bool:
14
+ pyproject = directory / "pyproject.toml"
15
+ if not pyproject.is_file() or (directory / CONFIG_FILENAME).is_file():
16
+ return False
17
+ text = pyproject.read_text(encoding="utf-8", errors="ignore")
18
+ return 'name = "org-wiki"' in text and (directory / "src" / "org_wiki").is_dir()
19
+
20
+
21
+ def resolve_workspace(explicit: str | Path | None = None) -> Path:
22
+ """Resolve the active wiki workspace directory."""
23
+ if explicit:
24
+ return Path(explicit).expanduser().resolve()
25
+
26
+ env_ws = (os.environ.get("ORGWIKI_WORKSPACE") or "").strip()
27
+ if env_ws:
28
+ return Path(env_ws).expanduser().resolve()
29
+
30
+ caller_cwd = (os.environ.get("ORGWIKI_CALLER_CWD") or "").strip()
31
+ start = Path(caller_cwd).resolve() if caller_cwd else Path.cwd().resolve()
32
+
33
+ for candidate in (start, *start.parents):
34
+ if (candidate / CONFIG_FILENAME).is_file():
35
+ return candidate
36
+
37
+ if _is_tool_source_repo(start):
38
+ return (start / "wiki-data").resolve()
39
+
40
+ return start
@@ -0,0 +1,158 @@
1
+ """Heading-aware Markdown chunker for knowledgebase indexing."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import dataclass
7
+ from pathlib import Path
8
+
9
+ HEADING_RE = re.compile(r"^(#{1,4})\s+(.+?)\s*$")
10
+ MAX_CHUNK_CHARS = 2200
11
+ SKIP_DIRS = {".git", ".venv", ".wiki-cache", ".kb-cache", "node_modules", "_templates", "onboarding", "__pycache__"}
12
+
13
+ CATEGORY_PREFIXES = (
14
+ ("00-infra", "infra"),
15
+ ("01-system-map", "system-map"),
16
+ ("02-runbooks", "runbooks"),
17
+ ("03-features", "features"),
18
+ ("04-decisions", "decisions"),
19
+ ("05-reference", "reference"),
20
+ )
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class MarkdownChunk:
25
+ """Single searchable section extracted from a Markdown file."""
26
+
27
+ path: str
28
+ category: str
29
+ doc_title: str
30
+ section_title: str
31
+ start_line: int
32
+ end_line: int
33
+ content: str
34
+ embed_text: str
35
+
36
+
37
+ def detect_category(rel_path: str) -> str:
38
+ for prefix, cat in CATEGORY_PREFIXES:
39
+ if rel_path.startswith(prefix):
40
+ return cat
41
+ return "general"
42
+
43
+
44
+ def list_markdown_files(root: Path) -> list[Path]:
45
+ """Return sorted Markdown files under workspace root, skipping internal folders."""
46
+ if not root.is_dir():
47
+ return []
48
+ found: list[Path] = []
49
+ for path in root.rglob("*.md"):
50
+ rel_parts = path.relative_to(root).parts
51
+ if any(part in SKIP_DIRS or part.startswith(".") for part in rel_parts[:-1]):
52
+ continue
53
+ if path.is_file():
54
+ found.append(path)
55
+ return sorted(found)
56
+
57
+
58
+ def chunk_markdown_file(root: Path, file_path: Path) -> list[MarkdownChunk]:
59
+ """Split a Markdown file by headings with size-bounded sub-windows."""
60
+ rel_path = str(file_path.relative_to(root)).replace("\\", "/")
61
+ category = detect_category(rel_path)
62
+ raw = file_path.read_text(encoding="utf-8", errors="ignore")
63
+ lines = raw.splitlines()
64
+ if not lines:
65
+ return []
66
+
67
+ doc_title = file_path.stem
68
+ for line in lines:
69
+ m = HEADING_RE.match(line)
70
+ if m and len(m.group(1)) == 1:
71
+ doc_title = m.group(2).strip()
72
+ break
73
+
74
+ sections: list[tuple[str, int, int, list[str]]] = []
75
+ cur_title = doc_title
76
+ cur_start = 1
77
+ cur_lines: list[str] = []
78
+
79
+ for line_no, line in enumerate(lines, start=1):
80
+ m = HEADING_RE.match(line)
81
+ if m and len(m.group(1)) in (2, 3) and cur_lines:
82
+ sections.append((cur_title, cur_start, line_no - 1, cur_lines))
83
+ cur_title = m.group(2).strip()
84
+ cur_start = line_no
85
+ cur_lines = [line]
86
+ else:
87
+ if m and len(m.group(1)) in (2, 3) and not cur_lines:
88
+ cur_title = m.group(2).strip()
89
+ cur_lines.append(line)
90
+
91
+ if cur_lines:
92
+ sections.append((cur_title, cur_start, len(lines), cur_lines))
93
+
94
+ chunks: list[MarkdownChunk] = []
95
+ for sec_title, start_line, end_line, sec_lines in sections:
96
+ text = "\n".join(sec_lines).strip()
97
+ if not text:
98
+ continue
99
+ if len(text) <= MAX_CHUNK_CHARS:
100
+ chunks.append(
101
+ _make_chunk(rel_path, category, doc_title, sec_title, start_line, end_line, text)
102
+ )
103
+ continue
104
+
105
+ buf: list[str] = []
106
+ buf_chars = 0
107
+ sub_start = start_line
108
+ for offset, ln in enumerate(sec_lines):
109
+ if buf and buf_chars + len(ln) + 1 > MAX_CHUNK_CHARS:
110
+ sub_text = "\n".join(buf).strip()
111
+ if sub_text:
112
+ chunks.append(
113
+ _make_chunk(
114
+ rel_path,
115
+ category,
116
+ doc_title,
117
+ sec_title,
118
+ sub_start,
119
+ start_line + offset - 1,
120
+ sub_text,
121
+ )
122
+ )
123
+ buf = [ln]
124
+ buf_chars = len(ln)
125
+ sub_start = start_line + offset
126
+ else:
127
+ buf.append(ln)
128
+ buf_chars += len(ln) + 1
129
+ if buf:
130
+ sub_text = "\n".join(buf).strip()
131
+ if sub_text:
132
+ chunks.append(
133
+ _make_chunk(rel_path, category, doc_title, sec_title, sub_start, end_line, sub_text)
134
+ )
135
+
136
+ return chunks
137
+
138
+
139
+ def _make_chunk(
140
+ rel_path: str,
141
+ category: str,
142
+ doc_title: str,
143
+ section_title: str,
144
+ start_line: int,
145
+ end_line: int,
146
+ content: str,
147
+ ) -> MarkdownChunk:
148
+ embed_text = f"Document: {doc_title} ({rel_path})\nSection: {section_title}\n\n{content}"
149
+ return MarkdownChunk(
150
+ path=rel_path,
151
+ category=category,
152
+ doc_title=doc_title,
153
+ section_title=section_title,
154
+ start_line=start_line,
155
+ end_line=end_line,
156
+ content=content,
157
+ embed_text=embed_text,
158
+ )