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 +21 -0
- org_wiki-0.1.0/PKG-INFO +203 -0
- org_wiki-0.1.0/README.md +175 -0
- org_wiki-0.1.0/pyproject.toml +57 -0
- org_wiki-0.1.0/setup.cfg +4 -0
- org_wiki-0.1.0/src/org_wiki/__init__.py +40 -0
- org_wiki-0.1.0/src/org_wiki/chunker.py +158 -0
- org_wiki-0.1.0/src/org_wiki/cli.py +328 -0
- org_wiki-0.1.0/src/org_wiki/config.py +156 -0
- org_wiki-0.1.0/src/org_wiki/drafter.py +254 -0
- org_wiki-0.1.0/src/org_wiki/gh_auth.py +252 -0
- org_wiki-0.1.0/src/org_wiki/harvester.py +751 -0
- org_wiki-0.1.0/src/org_wiki/llm.py +230 -0
- org_wiki-0.1.0/src/org_wiki/mcp_server.py +306 -0
- org_wiki-0.1.0/src/org_wiki/onboarding.py +225 -0
- org_wiki-0.1.0/src/org_wiki/scaffold.py +322 -0
- org_wiki-0.1.0/src/org_wiki/store.py +473 -0
- org_wiki-0.1.0/src/org_wiki/web.py +1076 -0
- org_wiki-0.1.0/src/org_wiki.egg-info/PKG-INFO +203 -0
- org_wiki-0.1.0/src/org_wiki.egg-info/SOURCES.txt +23 -0
- org_wiki-0.1.0/src/org_wiki.egg-info/dependency_links.txt +1 -0
- org_wiki-0.1.0/src/org_wiki.egg-info/entry_points.txt +3 -0
- org_wiki-0.1.0/src/org_wiki.egg-info/requires.txt +2 -0
- org_wiki-0.1.0/src/org_wiki.egg-info/top_level.txt +1 -0
- org_wiki-0.1.0/tests/test_org_wiki.py +189 -0
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.
|
org_wiki-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
org_wiki-0.1.0/README.md
ADDED
|
@@ -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"]
|
org_wiki-0.1.0/setup.cfg
ADDED
|
@@ -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
|
+
)
|