org-wiki 0.1.0__py3-none-any.whl
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/__init__.py +40 -0
- org_wiki/chunker.py +158 -0
- org_wiki/cli.py +328 -0
- org_wiki/config.py +156 -0
- org_wiki/drafter.py +254 -0
- org_wiki/gh_auth.py +252 -0
- org_wiki/harvester.py +751 -0
- org_wiki/llm.py +230 -0
- org_wiki/mcp_server.py +306 -0
- org_wiki/onboarding.py +225 -0
- org_wiki/scaffold.py +322 -0
- org_wiki/store.py +473 -0
- org_wiki/web.py +1076 -0
- org_wiki-0.1.0.dist-info/METADATA +203 -0
- org_wiki-0.1.0.dist-info/RECORD +19 -0
- org_wiki-0.1.0.dist-info/WHEEL +5 -0
- org_wiki-0.1.0.dist-info/entry_points.txt +3 -0
- org_wiki-0.1.0.dist-info/licenses/LICENSE +21 -0
- org_wiki-0.1.0.dist-info/top_level.txt +1 -0
org_wiki/__init__.py
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
|
org_wiki/chunker.py
ADDED
|
@@ -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
|
+
)
|
org_wiki/cli.py
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
"""Unified command-line interface for org-wiki."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import shutil
|
|
9
|
+
import sys
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
from . import __version__, resolve_workspace
|
|
13
|
+
from .config import OrgWikiConfig, infer_domains_from_repos, is_initialized
|
|
14
|
+
from .drafter import draft_from_merged_pr
|
|
15
|
+
from .gh_auth import (
|
|
16
|
+
get_auth_status,
|
|
17
|
+
gh_installed,
|
|
18
|
+
list_accessible_owners,
|
|
19
|
+
list_owner_repos,
|
|
20
|
+
run_interactive_gh_login,
|
|
21
|
+
)
|
|
22
|
+
from .harvester import harvest_workspace
|
|
23
|
+
from .llm import active_llm_provider, answer_question
|
|
24
|
+
from .mcp_server import McpServer, install_mcp_client, mcp_config_snippets
|
|
25
|
+
from .onboarding import connect_product_repos, publish_wiki_repo
|
|
26
|
+
from .scaffold import scaffold_workspace
|
|
27
|
+
from .store import KnowledgeStore, default_model_cache_dir
|
|
28
|
+
from .web import run_web_server
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _print_hits(hits: list, show_body: bool = True) -> None:
|
|
32
|
+
if not hits:
|
|
33
|
+
print("No matching sections found.")
|
|
34
|
+
return
|
|
35
|
+
for idx, h in enumerate(hits, start=1):
|
|
36
|
+
print(
|
|
37
|
+
f"\n[{idx}] {h.path}:{h.start_line}-{h.end_line} "
|
|
38
|
+
f"({h.doc_title} > {h.section_title}) "
|
|
39
|
+
f"[score={h.score} sem={h.semantic_score} kw={h.keyword_score}]"
|
|
40
|
+
)
|
|
41
|
+
if show_body:
|
|
42
|
+
print("-" * 78)
|
|
43
|
+
print(h.content)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _prompt_input(prompt: str, default: str = "") -> str:
|
|
47
|
+
suffix = f" [{default}]" if default else ""
|
|
48
|
+
try:
|
|
49
|
+
raw = input(f"{prompt}{suffix}: ").strip()
|
|
50
|
+
except EOFError:
|
|
51
|
+
return default
|
|
52
|
+
return raw or default
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _cmd_init(workspace: Path, args: argparse.Namespace) -> int:
|
|
56
|
+
target = Path(args.dir).expanduser().resolve() if args.dir else workspace
|
|
57
|
+
interactive = sys.stdin.isatty() and not args.yes
|
|
58
|
+
|
|
59
|
+
auth = get_auth_status(target)
|
|
60
|
+
if not auth["authenticated"] and interactive and not args.offline:
|
|
61
|
+
print("GitHub CLI is not authenticated yet.")
|
|
62
|
+
if gh_installed():
|
|
63
|
+
ans = _prompt_input("Run `gh auth login` now so org-wiki can auto-discover your company repos? (Y/n)", "y")
|
|
64
|
+
if ans.lower().startswith("y"):
|
|
65
|
+
run_interactive_gh_login()
|
|
66
|
+
auth = get_auth_status(target)
|
|
67
|
+
|
|
68
|
+
owner = (args.org or "").strip()
|
|
69
|
+
if not owner and auth["authenticated"] and not args.offline:
|
|
70
|
+
owners = list_accessible_owners(target)
|
|
71
|
+
if interactive and owners:
|
|
72
|
+
print("\nAccessible GitHub accounts / organizations:")
|
|
73
|
+
for idx, item in enumerate(owners, start=1):
|
|
74
|
+
print(f" [{idx}] {item['login']} ({item['type']})")
|
|
75
|
+
choice = _prompt_input("Select number or type GitHub org/user name", "1")
|
|
76
|
+
if choice.isdigit() and 1 <= int(choice) <= len(owners):
|
|
77
|
+
owner = owners[int(choice) - 1]["login"]
|
|
78
|
+
else:
|
|
79
|
+
owner = choice
|
|
80
|
+
elif owners:
|
|
81
|
+
orgs_only = [o["login"] for o in owners if o["type"] == "Organization"]
|
|
82
|
+
owner = orgs_only[0] if orgs_only else owners[0]["login"]
|
|
83
|
+
|
|
84
|
+
default_company = args.company or (owner.capitalize() if owner else target.name or "Company")
|
|
85
|
+
company = _prompt_input("Company / team name", default_company) if interactive and not args.company else default_company
|
|
86
|
+
|
|
87
|
+
default_wiki_repo = args.wiki_repo or f"{(owner or company).lower()}-wiki"
|
|
88
|
+
wiki_repo = _prompt_input("Wiki repo name", default_wiki_repo) if interactive and not args.wiki_repo else default_wiki_repo
|
|
89
|
+
|
|
90
|
+
exclude_repos = [r.strip() for r in (args.exclude or "").split(",") if r.strip()]
|
|
91
|
+
include_repos = [r.strip() for r in (args.repos or "").split(",") if r.strip()]
|
|
92
|
+
|
|
93
|
+
discovered_names: list[str] = []
|
|
94
|
+
if owner and auth["authenticated"] and not args.offline:
|
|
95
|
+
print(f"Discovering repositories in `{owner}` via GitHub API...")
|
|
96
|
+
repos = list_owner_repos(owner, workspace=target)
|
|
97
|
+
active_repos = [
|
|
98
|
+
r for r in repos if not r.get("archived") and str(r["name"]) != wiki_repo and str(r["name"]) not in exclude_repos
|
|
99
|
+
]
|
|
100
|
+
discovered_names = [str(r["name"]) for r in active_repos]
|
|
101
|
+
print(f" Found {len(active_repos)} active repository(ies).")
|
|
102
|
+
if interactive and not include_repos and active_repos:
|
|
103
|
+
excl_raw = _prompt_input("Optional comma-separated repos to exclude (press Enter to include all)", "")
|
|
104
|
+
if excl_raw:
|
|
105
|
+
for item in excl_raw.split(","):
|
|
106
|
+
if item.strip():
|
|
107
|
+
exclude_repos.append(item.strip())
|
|
108
|
+
discovered_names = [n for n in discovered_names if n not in exclude_repos]
|
|
109
|
+
|
|
110
|
+
domains = infer_domains_from_repos(include_repos or discovered_names)
|
|
111
|
+
cfg = OrgWikiConfig(
|
|
112
|
+
company_name=company,
|
|
113
|
+
github_owner=owner,
|
|
114
|
+
wiki_repo=wiki_repo,
|
|
115
|
+
include_repos=include_repos,
|
|
116
|
+
exclude_repos=exclude_repos,
|
|
117
|
+
domains=domains,
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
created = scaffold_workspace(target, cfg, init_git=True)
|
|
121
|
+
print(f"Initialized workspace at {target} ({len(created)} starter file(s)).")
|
|
122
|
+
|
|
123
|
+
if not args.offline and (owner or args.source_root):
|
|
124
|
+
if args.source_root:
|
|
125
|
+
os.environ["ORGWIKI_SOURCE_ROOT"] = str(Path(args.source_root).expanduser().resolve())
|
|
126
|
+
print("Harvesting HTTP APIs, data models, queues, CI workflows & env vars...")
|
|
127
|
+
changed = harvest_workspace(target, cfg, progress_cb=lambda m: print(f" {m}", flush=True))
|
|
128
|
+
print(f"Harvested {len(changed)} reference file(s).")
|
|
129
|
+
|
|
130
|
+
if not args.no_index:
|
|
131
|
+
print("Building local hybrid semantic + BM25 index...")
|
|
132
|
+
stats = KnowledgeStore(target).ensure_indexed(force=True)
|
|
133
|
+
print(
|
|
134
|
+
f"Indexed {stats['total_files']} Markdown files ({stats['total_chunks']} chunks, "
|
|
135
|
+
f"vectors={'on' if stats['vectors_enabled'] else 'BM25-only'})."
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
print(f"\nReady! Run `org-wiki --workspace {target}` to open the Web UI, or `org-wiki ask \"...\"`.")
|
|
139
|
+
return 0
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _cmd_doctor(workspace: Path) -> int:
|
|
143
|
+
auth = get_auth_status(workspace)
|
|
144
|
+
llm = active_llm_provider(workspace)
|
|
145
|
+
report = {
|
|
146
|
+
"org_wiki_version": __version__,
|
|
147
|
+
"python": sys.version.split()[0],
|
|
148
|
+
"workspace": str(workspace),
|
|
149
|
+
"workspace_initialized": is_initialized(workspace),
|
|
150
|
+
"git_installed": shutil.which("git") is not None,
|
|
151
|
+
"gh_cli_installed": gh_installed(),
|
|
152
|
+
"github_auth": auth,
|
|
153
|
+
"model_cache_dir": str(default_model_cache_dir()),
|
|
154
|
+
"llm_provider": llm or "none (offline hybrid ONNX + BM25)",
|
|
155
|
+
}
|
|
156
|
+
print(json.dumps(report, indent=2))
|
|
157
|
+
return 0
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def main(argv: list[str] | None = None) -> int:
|
|
161
|
+
parser = argparse.ArgumentParser(
|
|
162
|
+
prog="org-wiki",
|
|
163
|
+
description="Single-box, self-updating company engineering wiki (GitHub harvest + offline hybrid search + Web UI + MCP).",
|
|
164
|
+
)
|
|
165
|
+
parser.add_argument("-w", "--workspace", help="Path to wiki workspace directory")
|
|
166
|
+
parser.add_argument("-v", "--version", action="version", version=f"org-wiki {__version__}")
|
|
167
|
+
|
|
168
|
+
sub = parser.add_subparsers(dest="cmd")
|
|
169
|
+
|
|
170
|
+
p_init = sub.add_parser("init", help="Easy-mode setup wizard (uses `gh auth` automatically)")
|
|
171
|
+
p_init.add_argument("--org", help="GitHub organization or user login")
|
|
172
|
+
p_init.add_argument("--company", help="Company or team display name")
|
|
173
|
+
p_init.add_argument("--wiki-repo", help="Name for the engineering wiki repository")
|
|
174
|
+
p_init.add_argument("--dir", help="Target directory for the wiki workspace")
|
|
175
|
+
p_init.add_argument("--repos", help="Comma-separated allowlist of repositories to include")
|
|
176
|
+
p_init.add_argument("--exclude", help="Comma-separated repositories to exclude")
|
|
177
|
+
p_init.add_argument("--source-root", help="Optional local directory of cloned repos instead of GitHub")
|
|
178
|
+
p_init.add_argument("--offline", action="store_true", help="Scaffold locally without calling GitHub")
|
|
179
|
+
p_init.add_argument("--no-index", action="store_true", help="Skip initial embedding index build")
|
|
180
|
+
p_init.add_argument("-y", "--yes", action="store_true", help="Non-interactive mode using defaults")
|
|
181
|
+
|
|
182
|
+
p_serve = sub.add_parser("serve", help="Start the single-box Web UI (setup wizard + search + Q&A + editor)")
|
|
183
|
+
p_serve.add_argument("--host", default="127.0.0.1")
|
|
184
|
+
p_serve.add_argument("--port", type=int, default=8787)
|
|
185
|
+
|
|
186
|
+
p_harvest = sub.add_parser("harvest", help="Deterministically harvest routes, models, queues, workflows & env vars")
|
|
187
|
+
p_harvest.add_argument("--repos", help="Optional comma-separated subset of repos")
|
|
188
|
+
p_harvest.add_argument("--check", action="store_true", help="Exit 1 if reference catalogs differ from source")
|
|
189
|
+
p_harvest.add_argument("--no-index", action="store_true", help="Skip re-indexing after harvest")
|
|
190
|
+
|
|
191
|
+
p_search = sub.add_parser("search", help="Offline hybrid ONNX semantic + SQLite BM25 search")
|
|
192
|
+
p_search.add_argument("query", nargs="+", help="Search query or exact symbol")
|
|
193
|
+
p_search.add_argument("-k", "--top-k", type=int, default=6)
|
|
194
|
+
p_search.add_argument("-c", "--category", default="all")
|
|
195
|
+
p_search.add_argument("--json", action="store_true")
|
|
196
|
+
|
|
197
|
+
p_ask = sub.add_parser("ask", help="Ask a natural-language question with cited sources")
|
|
198
|
+
p_ask.add_argument("question", nargs="+", help="Question to answer")
|
|
199
|
+
p_ask.add_argument("-k", "--top-k", type=int, default=6)
|
|
200
|
+
p_ask.add_argument("-c", "--category", default="all")
|
|
201
|
+
p_ask.add_argument("--offline", action="store_true", help="Skip LLM synthesis even if configured")
|
|
202
|
+
p_ask.add_argument("--json", action="store_true")
|
|
203
|
+
|
|
204
|
+
p_index = sub.add_parser("index", help="Build or refresh the local ONNX + SQLite FTS5 index")
|
|
205
|
+
p_index.add_argument("--force", action="store_true")
|
|
206
|
+
|
|
207
|
+
sub.add_parser("sync", help="Pull or re-harvest from GitHub and incrementally update local index")
|
|
208
|
+
|
|
209
|
+
p_mcp = sub.add_parser("mcp", help="Run stdio MCP server or install into Cursor / Claude Code")
|
|
210
|
+
p_mcp.add_argument("--install", choices=["cursor", "claude-code"], help="Register MCP server in your IDE")
|
|
211
|
+
p_mcp.add_argument("--print-config", action="store_true", help="Print MCP JSON & CLI snippets")
|
|
212
|
+
|
|
213
|
+
p_pub = sub.add_parser("publish-repo", help="Create `<org>/<wiki-repo>` on GitHub via `gh` and push")
|
|
214
|
+
p_pub.add_argument("--public", action="store_true", help="Create a public repository (default is private)")
|
|
215
|
+
|
|
216
|
+
p_conn = sub.add_parser("connect-repos", help="Open onboarding PRs across org repos for auto-sync on merge")
|
|
217
|
+
p_conn.add_argument("--repos", help="Optional comma-separated list of repos")
|
|
218
|
+
p_conn.add_argument("--apply", action="store_true", help="Create branches & PRs (default is dry-run)")
|
|
219
|
+
|
|
220
|
+
p_draft = sub.add_parser("draft-pr", help="Draft prose wiki updates from a merged product PR diff")
|
|
221
|
+
p_draft.add_argument("--repo", required=True, help="Source repository name")
|
|
222
|
+
p_draft.add_argument("--pr", required=True, help="Merged pull request number")
|
|
223
|
+
|
|
224
|
+
sub.add_parser("doctor", help="Check Python, `gh auth`, git, embedding cache, and LLM readiness")
|
|
225
|
+
|
|
226
|
+
args = parser.parse_args(argv)
|
|
227
|
+
workspace = resolve_workspace(args.workspace)
|
|
228
|
+
|
|
229
|
+
if args.cmd == "init":
|
|
230
|
+
return _cmd_init(workspace, args)
|
|
231
|
+
|
|
232
|
+
if args.cmd == "doctor":
|
|
233
|
+
return _cmd_doctor(workspace)
|
|
234
|
+
|
|
235
|
+
if args.cmd in (None, "serve"):
|
|
236
|
+
host = getattr(args, "host", "127.0.0.1")
|
|
237
|
+
port = getattr(args, "port", 8787)
|
|
238
|
+
return run_web_server(workspace, host=host, port=port)
|
|
239
|
+
|
|
240
|
+
if args.cmd == "mcp":
|
|
241
|
+
if args.print_config:
|
|
242
|
+
print(json.dumps(mcp_config_snippets(workspace), indent=2))
|
|
243
|
+
return 0
|
|
244
|
+
if args.install:
|
|
245
|
+
print(install_mcp_client(workspace, args.install))
|
|
246
|
+
return 0
|
|
247
|
+
return McpServer(workspace).serve_stdio()
|
|
248
|
+
|
|
249
|
+
if args.cmd == "harvest":
|
|
250
|
+
cfg = OrgWikiConfig.load(workspace)
|
|
251
|
+
explicit = [r.strip() for r in args.repos.split(",") if r.strip()] if args.repos else None
|
|
252
|
+
drifted = harvest_workspace(
|
|
253
|
+
workspace,
|
|
254
|
+
cfg,
|
|
255
|
+
check_only=args.check,
|
|
256
|
+
explicit_repos=explicit,
|
|
257
|
+
progress_cb=lambda m: print(f" {m}", flush=True),
|
|
258
|
+
)
|
|
259
|
+
if args.check and drifted:
|
|
260
|
+
print("Catalogs out of date: " + ", ".join(drifted))
|
|
261
|
+
return 1
|
|
262
|
+
print("Updated: " + (", ".join(drifted) if drifted else "already up to date"))
|
|
263
|
+
if not args.check and not args.no_index:
|
|
264
|
+
KnowledgeStore(workspace).ensure_indexed()
|
|
265
|
+
return 0
|
|
266
|
+
|
|
267
|
+
if args.cmd == "publish-repo":
|
|
268
|
+
cfg = OrgWikiConfig.load(workspace)
|
|
269
|
+
url = publish_wiki_repo(workspace, cfg, private=not args.public)
|
|
270
|
+
print(f"Published wiki to {url}")
|
|
271
|
+
return 0
|
|
272
|
+
|
|
273
|
+
if args.cmd == "connect-repos":
|
|
274
|
+
cfg = OrgWikiConfig.load(workspace)
|
|
275
|
+
explicit = [r.strip() for r in args.repos.split(",") if r.strip()] if args.repos else None
|
|
276
|
+
for line in connect_product_repos(workspace, cfg, explicit_repos=explicit, apply=args.apply):
|
|
277
|
+
print(" " + line)
|
|
278
|
+
return 0
|
|
279
|
+
|
|
280
|
+
if args.cmd == "draft-pr":
|
|
281
|
+
res = draft_from_merged_pr(workspace, source_repo=args.repo, pr_number=args.pr)
|
|
282
|
+
print(json.dumps(res, indent=2))
|
|
283
|
+
return 0
|
|
284
|
+
|
|
285
|
+
store = KnowledgeStore(workspace)
|
|
286
|
+
|
|
287
|
+
if args.cmd == "index":
|
|
288
|
+
print(json.dumps(store.ensure_indexed(force=args.force), indent=2))
|
|
289
|
+
return 0
|
|
290
|
+
|
|
291
|
+
if args.cmd == "sync":
|
|
292
|
+
print(json.dumps(store.sync_workspace(), indent=2))
|
|
293
|
+
return 0
|
|
294
|
+
|
|
295
|
+
if args.cmd == "search":
|
|
296
|
+
q = " ".join(args.query)
|
|
297
|
+
hits = store.search(q, top_k=args.top_k, category=args.category)
|
|
298
|
+
if args.json:
|
|
299
|
+
print(json.dumps([h.to_dict() for h in hits], indent=2))
|
|
300
|
+
else:
|
|
301
|
+
_print_hits(hits, show_body=True)
|
|
302
|
+
return 0
|
|
303
|
+
|
|
304
|
+
if args.cmd == "ask":
|
|
305
|
+
q = " ".join(args.question)
|
|
306
|
+
hits = store.search(q, top_k=args.top_k, category=args.category)
|
|
307
|
+
res = answer_question(workspace, q, hits, allow_llm=not args.offline)
|
|
308
|
+
if args.json:
|
|
309
|
+
print(json.dumps(res, indent=2))
|
|
310
|
+
return 0
|
|
311
|
+
if res.get("answer"):
|
|
312
|
+
print(f"\n=== Answer ({res['mode']}) ===\n")
|
|
313
|
+
print(res["answer"])
|
|
314
|
+
print("\n=== Cited Sources ===")
|
|
315
|
+
_print_hits(hits, show_body=False)
|
|
316
|
+
else:
|
|
317
|
+
if res.get("llm_error"):
|
|
318
|
+
print(f"Note: {res['llm_error']}\n", file=sys.stderr)
|
|
319
|
+
print("=== Top Hybrid Matches (Offline Mode — set ANTHROPIC_API_KEY, OPENAI_API_KEY, OLLAMA_MODEL, or ORGWIKI_USE_GH_MODELS=1 for prose synthesis) ===")
|
|
320
|
+
_print_hits(hits, show_body=True)
|
|
321
|
+
return 0
|
|
322
|
+
|
|
323
|
+
parser.print_help()
|
|
324
|
+
return 1
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
if __name__ == "__main__":
|
|
328
|
+
sys.exit(main())
|
org_wiki/config.py
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Configuration loader and serializer for org-wiki.toml."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ast
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
try:
|
|
10
|
+
import tomllib
|
|
11
|
+
except ModuleNotFoundError:
|
|
12
|
+
tomllib = None
|
|
13
|
+
|
|
14
|
+
from . import CONFIG_FILENAME
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass
|
|
18
|
+
class OrgWikiConfig:
|
|
19
|
+
"""Workspace-level configuration stored in org-wiki.toml."""
|
|
20
|
+
|
|
21
|
+
company_name: str = "Company"
|
|
22
|
+
github_owner: str = ""
|
|
23
|
+
wiki_repo: str = "company-wiki"
|
|
24
|
+
default_branch: str = "main"
|
|
25
|
+
include_repos: list[str] = field(default_factory=list)
|
|
26
|
+
exclude_repos: list[str] = field(default_factory=list)
|
|
27
|
+
domains: dict[str, list[str]] = field(default_factory=dict)
|
|
28
|
+
|
|
29
|
+
@property
|
|
30
|
+
def config_title(self) -> str:
|
|
31
|
+
return f"{self.company_name} Wiki"
|
|
32
|
+
|
|
33
|
+
def is_repo_selected(self, repo_name: str) -> bool:
|
|
34
|
+
if repo_name == self.wiki_repo or repo_name in self.exclude_repos:
|
|
35
|
+
return False
|
|
36
|
+
if self.include_repos:
|
|
37
|
+
return repo_name in self.include_repos
|
|
38
|
+
return True
|
|
39
|
+
|
|
40
|
+
def domain_for_repo(self, repo_name: str) -> str:
|
|
41
|
+
for domain, patterns in self.domains.items():
|
|
42
|
+
for pat in patterns:
|
|
43
|
+
if pat.endswith("*") and repo_name.startswith(pat[:-1]):
|
|
44
|
+
return domain
|
|
45
|
+
if repo_name == pat or repo_name.startswith(f"{pat}-"):
|
|
46
|
+
return domain
|
|
47
|
+
if "-" in repo_name:
|
|
48
|
+
prefix = repo_name.split("-", 1)[0]
|
|
49
|
+
if len(prefix) >= 3 and prefix not in {"api", "app", "web", "svc", "service", "backend", "frontend"}:
|
|
50
|
+
return prefix.capitalize()
|
|
51
|
+
return "Core Platform"
|
|
52
|
+
|
|
53
|
+
def domain_slug_for_repo(self, repo_name: str) -> str:
|
|
54
|
+
raw = self.domain_for_repo(repo_name).lower()
|
|
55
|
+
slug = "".join(ch if ch.isalnum() else "-" for ch in raw).strip("-")
|
|
56
|
+
while "--" in slug:
|
|
57
|
+
slug = slug.replace("--", "-")
|
|
58
|
+
return slug or "platform"
|
|
59
|
+
|
|
60
|
+
def to_toml(self) -> str:
|
|
61
|
+
lines = [
|
|
62
|
+
f"company_name = {_toml_str(self.company_name)}",
|
|
63
|
+
f"github_owner = {_toml_str(self.github_owner)}",
|
|
64
|
+
f"wiki_repo = {_toml_str(self.wiki_repo)}",
|
|
65
|
+
f"default_branch = {_toml_str(self.default_branch)}",
|
|
66
|
+
f"include_repos = {_toml_list(self.include_repos)}",
|
|
67
|
+
f"exclude_repos = {_toml_list(self.exclude_repos)}",
|
|
68
|
+
"",
|
|
69
|
+
"[domains]",
|
|
70
|
+
]
|
|
71
|
+
for domain, patterns in sorted(self.domains.items()):
|
|
72
|
+
lines.append(f"{_toml_key(domain)} = {_toml_list(patterns)}")
|
|
73
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
74
|
+
|
|
75
|
+
def save(self, workspace: Path) -> Path:
|
|
76
|
+
workspace.mkdir(parents=True, exist_ok=True)
|
|
77
|
+
path = workspace / CONFIG_FILENAME
|
|
78
|
+
path.write_text(self.to_toml(), encoding="utf-8")
|
|
79
|
+
return path
|
|
80
|
+
|
|
81
|
+
@classmethod
|
|
82
|
+
def load(cls, workspace: Path) -> OrgWikiConfig:
|
|
83
|
+
path = workspace / CONFIG_FILENAME
|
|
84
|
+
if not path.is_file():
|
|
85
|
+
return cls(company_name=workspace.name or "Company")
|
|
86
|
+
raw = path.read_text(encoding="utf-8")
|
|
87
|
+
data = tomllib.loads(raw) if tomllib is not None else _fallback_parse_toml(raw)
|
|
88
|
+
domains_raw = data.get("domains") or {}
|
|
89
|
+
domains = {str(k): [str(x) for x in v] for k, v in domains_raw.items() if isinstance(v, list)}
|
|
90
|
+
return cls(
|
|
91
|
+
company_name=str(data.get("company_name") or "Company"),
|
|
92
|
+
github_owner=str(data.get("github_owner") or ""),
|
|
93
|
+
wiki_repo=str(data.get("wiki_repo") or data.get("kb_repo") or "company-wiki"),
|
|
94
|
+
default_branch=str(data.get("default_branch") or "main"),
|
|
95
|
+
include_repos=[str(x) for x in (data.get("include_repos") or [])],
|
|
96
|
+
exclude_repos=[str(x) for x in (data.get("exclude_repos") or [])],
|
|
97
|
+
domains=domains,
|
|
98
|
+
)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def is_initialized(workspace: Path) -> bool:
|
|
102
|
+
return (workspace / CONFIG_FILENAME).is_file()
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def infer_domains_from_repos(repo_names: list[str]) -> dict[str, list[str]]:
|
|
106
|
+
"""Group repository prefixes automatically when >=2 repos share a meaningful prefix."""
|
|
107
|
+
ignored = {"api", "app", "web", "svc", "service", "services", "lib", "pkg", "go", "py", "js", "ts"}
|
|
108
|
+
buckets: dict[str, list[str]] = {}
|
|
109
|
+
for name in sorted(repo_names):
|
|
110
|
+
if "-" not in name:
|
|
111
|
+
continue
|
|
112
|
+
prefix = name.split("-", 1)[0].lower()
|
|
113
|
+
if len(prefix) < 3 or prefix in ignored:
|
|
114
|
+
continue
|
|
115
|
+
buckets.setdefault(prefix, []).append(name)
|
|
116
|
+
|
|
117
|
+
domains: dict[str, list[str]] = {}
|
|
118
|
+
for prefix, members in sorted(buckets.items()):
|
|
119
|
+
if len(members) >= 2:
|
|
120
|
+
domains[prefix.capitalize()] = [f"{prefix}-*"]
|
|
121
|
+
return domains
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _toml_str(val: str) -> str:
|
|
125
|
+
escaped = val.replace("\\", "\\\\").replace('"', '\\"')
|
|
126
|
+
return f'"{escaped}"'
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _toml_key(key: str) -> str:
|
|
130
|
+
if key.isalnum() or all(c.isalnum() or c in "-_" for c in key):
|
|
131
|
+
return key
|
|
132
|
+
return _toml_str(key)
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _toml_list(items: list[str]) -> str:
|
|
136
|
+
if not items:
|
|
137
|
+
return "[]"
|
|
138
|
+
return "[" + ", ".join(_toml_str(x) for x in items) + "]"
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _fallback_parse_toml(raw: str) -> dict:
|
|
142
|
+
result: dict = {}
|
|
143
|
+
section: dict = result
|
|
144
|
+
for line in raw.splitlines():
|
|
145
|
+
stripped = line.strip()
|
|
146
|
+
if not stripped or stripped.startswith("#"):
|
|
147
|
+
continue
|
|
148
|
+
if stripped.startswith("[") and stripped.endswith("]"):
|
|
149
|
+
sec_name = stripped[1:-1].strip().strip('"')
|
|
150
|
+
section = result.setdefault(sec_name, {})
|
|
151
|
+
continue
|
|
152
|
+
if "=" in stripped:
|
|
153
|
+
k, v = stripped.split("=", 1)
|
|
154
|
+
key = k.strip().strip('"')
|
|
155
|
+
section[key] = ast.literal_eval(v.strip())
|
|
156
|
+
return result
|