|
| 1 | +"""Scaffold a new LOKF knowledge-base repository. |
| 2 | +
|
| 3 | +`lokf new my-kb` writes a self-contained repo from the packaged template |
| 4 | +(``lokf/templates/kb``): a starter **bundle** (``knowledge/``), a full **Astro |
| 5 | +site** that renders the concepts and ships the interactive **graph browser** |
| 6 | +(``/graph``) plus the ``graph.json`` / ``graph.jsonld`` projections, a GitHub |
| 7 | +**Pages workflow**, a ``justfile`` that also drives the ``lokf`` toolkit via |
| 8 | +``uvx``, and the bundled **agent skills** so an AI agent can author the |
| 9 | +knowledge base from a prompt. In the spirit of linkml-cookiecutter: scaffold, |
| 10 | +then start authoring (or point Claude at it). |
| 11 | +""" |
| 12 | +from __future__ import annotations |
| 13 | + |
| 14 | +import pathlib |
| 15 | +from importlib import resources |
| 16 | +from urllib.parse import urlsplit |
| 17 | + |
| 18 | +from lokf import agentskills |
| 19 | + |
| 20 | +#: Path segments renamed on copy — dotfiles are stored dot-free so packaging |
| 21 | +#: tools never skip them. |
| 22 | +RENAMES = {"_github": ".github", "_gitignore": ".gitignore"} |
| 23 | + |
| 24 | + |
| 25 | +def template_dir() -> pathlib.Path: |
| 26 | + """Return the packaged knowledge-base template (``lokf/templates/kb``).""" |
| 27 | + return pathlib.Path(str(resources.files("lokf") / "templates" / "kb")) |
| 28 | + |
| 29 | + |
| 30 | +def _slug_title(name: str) -> str: |
| 31 | + return name.replace("-", " ").replace("_", " ").strip().title() |
| 32 | + |
| 33 | + |
| 34 | +def _tokens(name: str, title: str, base_iri: str) -> dict[str, str]: |
| 35 | + """The substitution map applied to every template file. |
| 36 | +
|
| 37 | + ``site``/``base`` are split out of the base IRI so the Astro site works |
| 38 | + both at a domain root (base "/") and as a GitHub *project* page |
| 39 | + (base "/<repo>"). |
| 40 | + """ |
| 41 | + parts = urlsplit(base_iri) |
| 42 | + site = f"{parts.scheme}://{parts.netloc}" |
| 43 | + base = parts.path.rstrip("/") or "/" |
| 44 | + return { |
| 45 | + "__KB_NAME__": name, |
| 46 | + "__KB_TITLE__": title, |
| 47 | + "__KB_BASE_IRI__": base_iri, |
| 48 | + "__KB_SITE__": site, |
| 49 | + "__KB_BASE__": base, |
| 50 | + } |
| 51 | + |
| 52 | + |
| 53 | +def new(name: str, path: str | pathlib.Path = ".", |
| 54 | + title: str | None = None, base_iri: str | None = None) -> pathlib.Path: |
| 55 | + """Create a new knowledge-base repo *name* under *path*; return its root. |
| 56 | +
|
| 57 | + Refuses to overwrite an existing non-empty directory. |
| 58 | + """ |
| 59 | + title = title or _slug_title(name) |
| 60 | + base_iri = base_iri or f"https://example.org/{name}/" |
| 61 | + if not base_iri.endswith("/"): |
| 62 | + base_iri += "/" |
| 63 | + |
| 64 | + root = pathlib.Path(path) / name |
| 65 | + if root.exists() and (root.is_file() or any(root.iterdir())): |
| 66 | + raise FileExistsError(f"{root} already exists and is not empty") |
| 67 | + |
| 68 | + tdir = template_dir() |
| 69 | + if not tdir.is_dir(): |
| 70 | + raise RuntimeError(f"packaged knowledge-base template not found at {tdir}") |
| 71 | + tokens = _tokens(name, title, base_iri) |
| 72 | + for src in sorted(tdir.rglob("*")): |
| 73 | + if not src.is_file(): |
| 74 | + continue |
| 75 | + rel = tuple(RENAMES.get(p, p) for p in src.relative_to(tdir).parts) |
| 76 | + dest = root.joinpath(*rel) |
| 77 | + dest.parent.mkdir(parents=True, exist_ok=True) |
| 78 | + text = src.read_text(encoding="utf-8") |
| 79 | + for token, value in tokens.items(): |
| 80 | + text = text.replace(token, value) |
| 81 | + dest.write_text(text, encoding="utf-8") |
| 82 | + |
| 83 | + # Drop the bundled agent skills in so an AI agent can author the KB. |
| 84 | + agentskills.install(root / ".claude" / "skills") |
| 85 | + return root |
0 commit comments