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 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