torben
7263f85936
Files changed: - .gitignore - AGENTS.md - CHANGES.md - VERSION - instructions/gates.md - instructions/private-instance.md - tools/chemenu/commands/doctor.py - tools/chemenu/commands/git_publish.py - tools/chemenu/config.py - tools/chemenu/tests/test_git_publish.py
425 lines
16 KiB
Python
425 lines
16 KiB
Python
"""`wikitool doctor` - one deterministic health check for a wiki instance.
|
|
|
|
Read-only, never writes. Exists to back `instructions/setup-instance.md` (and
|
|
any other instance-setup procedure) with a single command instead of ten
|
|
individual checks spelled out in prose - the same reasoning that keeps
|
|
mechanical work in code everywhere else in this repo. Each check reports
|
|
`OK`, `WARN`, or `FAIL` plus, on anything but `OK`, the command to fix it.
|
|
Only a `FAIL` makes the overall exit code non-zero: a fresh instance with no
|
|
remote yet, or no `WIKITOOL_SESSION_ID` set, is a valid state, not a fault.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import json as _json
|
|
import shutil
|
|
import subprocess
|
|
import sys
|
|
from dataclasses import dataclass
|
|
from typing import Optional
|
|
|
|
import typer
|
|
from rich.console import Console
|
|
|
|
from chemenu import config, kb_collections, version as version_mod
|
|
from chemenu.commands import git_publish, instructions_cmd
|
|
from chemenu.commands._util import rel_path
|
|
from chemenu.session import ENV_VAR as SESSION_ENV_VAR
|
|
|
|
console = Console()
|
|
|
|
|
|
@dataclass
|
|
class Check:
|
|
name: str
|
|
status: str # "OK" | "WARN" | "FAIL"
|
|
detail: str
|
|
fix: Optional[str] = None
|
|
|
|
|
|
def _git(args: list[str]) -> Optional[subprocess.CompletedProcess]:
|
|
try:
|
|
return subprocess.run(
|
|
["git", *args], cwd=config.ROOT, capture_output=True, text=True, timeout=5
|
|
)
|
|
except (OSError, subprocess.SubprocessError):
|
|
return None
|
|
|
|
|
|
def check_python() -> Check:
|
|
version = sys.version_info
|
|
if version < (3, 11):
|
|
return Check(
|
|
"python", "FAIL", f"Python {version.major}.{version.minor} found, need >= 3.11",
|
|
"Install Python 3.11+ and recreate tools/.venv",
|
|
)
|
|
return Check("python", "OK", f"Python {version.major}.{version.minor}.{version.micro}")
|
|
|
|
|
|
def check_ripgrep() -> Check:
|
|
if shutil.which("rg"):
|
|
return Check("ripgrep", "OK", "rg found on PATH")
|
|
return Check(
|
|
"ripgrep", "FAIL", "rg not found on PATH - `search` and `sources coverage` need it",
|
|
"Install ripgrep (e.g. `apt install ripgrep` / `brew install ripgrep`)",
|
|
)
|
|
|
|
|
|
def check_author() -> Check:
|
|
author = config.default_author()
|
|
if author is None:
|
|
return Check(
|
|
"author", "FAIL", "Neither $WIKI_AUTHOR nor `git config user.name` resolves",
|
|
"Run `git config user.name \"<Your Name>\"`, or export WIKI_AUTHOR",
|
|
)
|
|
import os
|
|
|
|
source = "WIKI_AUTHOR" if os.environ.get("WIKI_AUTHOR", "").strip() else "git config user.name"
|
|
return Check("author", "OK", f"'{author}' (from {source})")
|
|
|
|
|
|
def check_git_repo() -> list[Check]:
|
|
checks: list[Check] = []
|
|
inside = _git(["rev-parse", "--is-inside-work-tree"])
|
|
if inside is None or inside.returncode != 0 or inside.stdout.strip() != "true":
|
|
checks.append(
|
|
Check(
|
|
"git-repo", "FAIL", "Not inside a git working tree",
|
|
"Run `git init -b main`",
|
|
)
|
|
)
|
|
return checks
|
|
checks.append(Check("git-repo", "OK", "Inside a git working tree"))
|
|
|
|
name = _git(["config", "user.name"])
|
|
email = _git(["config", "user.email"])
|
|
if not name or not name.stdout.strip():
|
|
checks.append(
|
|
Check("git-identity", "FAIL", "`git config user.name` is not set",
|
|
"Run `git config user.name \"<Your Name>\"`")
|
|
)
|
|
elif not email or not email.stdout.strip():
|
|
checks.append(
|
|
Check("git-identity", "FAIL", "`git config user.email` is not set",
|
|
"Run `git config user.email \"<you@example.com>\"`")
|
|
)
|
|
else:
|
|
checks.append(Check("git-identity", "OK", f"{name.stdout.strip()} <{email.stdout.strip()}>"))
|
|
|
|
branch = _git(["rev-parse", "--abbrev-ref", "HEAD"])
|
|
branch_name = branch.stdout.strip() if branch and branch.returncode == 0 else ""
|
|
if not branch_name or branch_name == "HEAD":
|
|
checks.append(
|
|
Check("git-branch", "WARN", "No commit yet, or detached HEAD",
|
|
"Make the first commit via `publish` once ready")
|
|
)
|
|
else:
|
|
checks.append(Check("git-branch", "OK", f"On branch '{branch_name}'"))
|
|
|
|
remote = _git(["remote", "get-url", "origin"])
|
|
if remote and remote.returncode == 0 and remote.stdout.strip():
|
|
checks.append(Check("git-remote", "OK", remote.stdout.strip()))
|
|
else:
|
|
checks.append(
|
|
Check(
|
|
"git-remote", "WARN", "No 'origin' remote configured",
|
|
"A local-only instance is valid - `git remote add origin <url>` if you want one. "
|
|
"Every `publish` needs --no-push until then",
|
|
)
|
|
)
|
|
return checks
|
|
|
|
|
|
def check_skills() -> Check:
|
|
sources = instructions_cmd.skill_dirs()
|
|
if not sources:
|
|
return Check("skills", "FAIL", "No skills found under instructions/", None)
|
|
target_dirs = instructions_cmd.target_dirs()
|
|
missing = 0
|
|
drifted: list[str] = []
|
|
for target_root in target_dirs:
|
|
for source in sources:
|
|
difference = instructions_cmd.drift(source, target_root / source.name)
|
|
if difference == "missing":
|
|
missing += 1
|
|
elif difference:
|
|
drifted.append(f"{rel_path(target_root / source.name)}: {difference}")
|
|
expected = len(sources) * len(target_dirs)
|
|
if missing == expected and not drifted:
|
|
return Check(
|
|
"skills", "FAIL", "No skills published yet",
|
|
"Run `tools/wikitool instructions sync`",
|
|
)
|
|
if drifted:
|
|
return Check(
|
|
"skills", "FAIL", f"{len(drifted)} published copy/copies drifted from source",
|
|
"Run `tools/wikitool instructions sync`",
|
|
)
|
|
return Check("skills", "OK", f"{expected} published copy/copies match their source")
|
|
|
|
|
|
def check_structure() -> Check:
|
|
missing = []
|
|
for relative_path in (
|
|
"kb/CONTRACT.md", "raw/CONTRACT.md", "reports/CONTRACT.md",
|
|
"work/CONTRACT.md", "instructions/CONTRACT.md", "types/type-spec.md",
|
|
):
|
|
if not (config.ROOT / relative_path).exists():
|
|
missing.append(relative_path)
|
|
collections = kb_collections.iter_kb_collections()
|
|
if not collections:
|
|
missing.append("kb/*/COLLECTION.md")
|
|
if missing:
|
|
return Check(
|
|
"structure", "FAIL", f"Missing: {', '.join(missing)}",
|
|
"Re-run `dist export`, or restore the missing contract(s) from the source repo",
|
|
)
|
|
return Check(
|
|
"structure", "OK", f"{len(collections)} collection(s), all stage contracts present"
|
|
)
|
|
|
|
|
|
def check_personalization() -> Check:
|
|
"""Whether this instance knows who it works for, and how it sounds.
|
|
|
|
`USER.md` and `SOUL.md` are read every session, so an instance without
|
|
them runs a generic agent against a wiki built for one person - which is
|
|
a fault, not a preference, hence `FAIL` rather than `WARN`. They are also
|
|
the one pair of required files a distribution cannot ship filled: their
|
|
content is personal, so `dist export` carries the templates and the
|
|
Personalization step of `setup-instance.md` writes the real ones. That
|
|
makes a still-templated file the second failure mode worth naming
|
|
separately - it looks present and answers nothing.
|
|
"""
|
|
missing: list[str] = []
|
|
unfilled: list[str] = []
|
|
for name in config.PERSONALIZATION_FILES:
|
|
path = config.ROOT / name
|
|
if not path.is_file():
|
|
missing.append(name)
|
|
elif config.TEMPLATE_SENTINEL in path.read_text(encoding="utf-8"):
|
|
unfilled.append(name)
|
|
|
|
fix = (
|
|
"Run the Personalization step of instructions/setup-instance.md - it interviews you "
|
|
f"along {' and '.join(config.PERSONALIZATION_TEMPLATES)} and writes your answers verbatim"
|
|
)
|
|
if missing:
|
|
return Check("personalization", "FAIL", f"Missing: {', '.join(missing)}", fix)
|
|
if unfilled:
|
|
return Check(
|
|
"personalization", "FAIL",
|
|
f"Still the unfilled template: {', '.join(unfilled)}", fix,
|
|
)
|
|
return Check("personalization", "OK", f"{', '.join(config.PERSONALIZATION_FILES)} present and filled")
|
|
|
|
|
|
def check_environment() -> Check:
|
|
"""Whether this checkout records the environment it works through.
|
|
|
|
`ENVIRONMENT.md` names the harness, the published skills, the MCP
|
|
servers, the connectors and the git remotes this working copy actually
|
|
uses. Missing it costs a session some questions, not correctness, so this
|
|
check never FAILs - the whole point of the file is that it is optional,
|
|
and a FAIL would make it mandatory by the back door.
|
|
|
|
The one thing worth reporting is the failure mode the personalization
|
|
check already knows: a template renamed but not filled in. That file is
|
|
present, is loaded into every session, and answers nothing - worse than
|
|
absence, because absence is honest.
|
|
"""
|
|
path = config.ROOT / config.ENVIRONMENT_FILE
|
|
if not path.is_file():
|
|
return Check(
|
|
"environment", "OK", f"{config.ENVIRONMENT_FILE} absent (optional)",
|
|
)
|
|
if config.TEMPLATE_SENTINEL in path.read_text(encoding="utf-8"):
|
|
return Check(
|
|
"environment", "WARN",
|
|
f"{config.ENVIRONMENT_FILE} is still the unfilled template",
|
|
f"Fill it in along {config.ENVIRONMENT_TEMPLATE}'s sections and drop the "
|
|
f"`{config.TEMPLATE_SENTINEL}` line, or delete the file - it is optional",
|
|
)
|
|
return Check("environment", "OK", f"{config.ENVIRONMENT_FILE} present and filled")
|
|
|
|
|
|
def check_publish_remotes() -> Check:
|
|
"""Whether the Publish-Remote Gate is armed in this checkout.
|
|
|
|
Absent is a legitimate state, not a fault: a checkout with a single remote
|
|
and nothing private in it has nothing to protect, and making the file
|
|
mandatory would turn a safeguard into paperwork. So this never FAILs - it
|
|
reports, the way `environment` does.
|
|
|
|
It does WARN for the case that actually bites: more than one remote
|
|
configured and no allowlist. That is the shape a private instance has after
|
|
it adds the public upstream, and it is exactly when a wrong `--remote`
|
|
stops being a typo and starts being a disclosure.
|
|
"""
|
|
urls = git_publish.read_allowed_push_urls()
|
|
if urls is not None:
|
|
return Check(
|
|
"publish-remotes", "OK",
|
|
f"{len(urls)} allowed push target(s) in {config.PUBLISH_REMOTES_FILENAME}",
|
|
)
|
|
result = subprocess.run(
|
|
["git", "remote"], cwd=config.ROOT, capture_output=True, text=True
|
|
)
|
|
remotes = [r for r in result.stdout.split() if r]
|
|
if len(remotes) > 1:
|
|
return Check(
|
|
"publish-remotes", "WARN",
|
|
f"{len(remotes)} remotes ({', '.join(remotes)}) and no publish allowlist",
|
|
f"Create {config.PUBLISH_REMOTES_FILENAME} naming the push URL this checkout "
|
|
"may publish to - see instructions/gates.md",
|
|
)
|
|
return Check(
|
|
"publish-remotes", "OK",
|
|
f"No {config.PUBLISH_REMOTES_FILENAME} (unrestricted; one remote configured)",
|
|
)
|
|
|
|
|
|
def check_generated_files() -> Check:
|
|
missing = [
|
|
rel_path(path)
|
|
for path in (config.INDEX_FILE, config.LOG_FILE, config.PROVENANCE_FILE)
|
|
if not path.exists()
|
|
]
|
|
if missing:
|
|
return Check(
|
|
"generated-files", "FAIL", f"Missing: {', '.join(missing)}",
|
|
"Run `index rebuild` and `sources rebuild-index`",
|
|
)
|
|
return Check("generated-files", "OK", "kb/index.md, kb/log.md, kb/provenance.md present")
|
|
|
|
|
|
def check_session_id() -> Check:
|
|
import os
|
|
|
|
if os.environ.get(SESSION_ENV_VAR, "").strip():
|
|
return Check("session-id", "OK", f"{SESSION_ENV_VAR}={os.environ[SESSION_ENV_VAR]}")
|
|
return Check(
|
|
"session-id", "WARN", f"{SESSION_ENV_VAR} is not set - budget falls back to the parent PID",
|
|
"See instructions/session-setup.md",
|
|
)
|
|
|
|
|
|
def check_stack_version() -> Check:
|
|
"""Which stack this instance runs, and where it came from.
|
|
|
|
A missing `VERSION` is a WARN, not a FAIL: instances exported before the
|
|
stack was versioned are still perfectly functional - they just cannot
|
|
answer `version check`. A malformed one is a FAIL, because then something
|
|
edited a generated fact by hand and every comparison built on it is wrong.
|
|
"""
|
|
try:
|
|
current = version_mod.read_version()
|
|
except version_mod.VersionError as exc:
|
|
if not version_mod.version_file().is_file():
|
|
return Check(
|
|
"stack-version", "WARN", "No VERSION file - this instance predates stack versioning",
|
|
"Re-export from a current origin, or write the version this instance corresponds to",
|
|
)
|
|
return Check("stack-version", "FAIL", str(exc), f"Fix {version_mod.VERSION_FILENAME} by hand - it holds one semantic version, nothing else")
|
|
|
|
try:
|
|
stamp = version_mod.read_stamp()
|
|
except version_mod.VersionError as exc:
|
|
return Check(
|
|
"stack-version", "FAIL", str(exc),
|
|
f"Delete {version_mod.RELEASE_STAMP_FILENAME} or restore it from the release it came from",
|
|
)
|
|
|
|
origin = "development tree" if stamp is None else f"distribution, exported {stamp.get('exported_at', 'unknown')}"
|
|
return Check("stack-version", "OK", f"{current} ({origin})")
|
|
|
|
|
|
def check_kb_version() -> Check:
|
|
"""Whether the content is in the shape this machinery expects.
|
|
|
|
A `WARN` when the content lags: that is the normal, transient state in the
|
|
middle of an upgrade, not a fault - and `migrate status` names the chain
|
|
that closes it. A missing declaration is also a `WARN` (an instance from
|
|
before the file existed still works), an unreadable one a `FAIL`.
|
|
"""
|
|
from chemenu import kb_state
|
|
|
|
try:
|
|
stack = version_mod.read_version()
|
|
except version_mod.VersionError:
|
|
return Check(
|
|
"kb-version", "WARN", "No stack version to compare the content against",
|
|
"See the stack-version check above",
|
|
)
|
|
try:
|
|
kb_version = kb_state.read_kb_version()
|
|
except version_mod.VersionError as exc:
|
|
return Check(
|
|
"kb-version", "FAIL", str(exc),
|
|
f"Restore or delete {kb_state.KB_STATE_FILENAME}, then "
|
|
"`tools/wikitool migrate baseline <version>`",
|
|
)
|
|
|
|
if kb_version is None:
|
|
return Check(
|
|
"kb-version", "WARN",
|
|
f"{kb_state.KB_STATE_FILENAME} is missing - the content's shape is undeclared",
|
|
f"Run `tools/wikitool migrate baseline {stack}` if this instance's content has "
|
|
"never lagged behind its machinery",
|
|
)
|
|
if kb_version < stack:
|
|
pending = kb_state.chain(kb_state.load_migrations(), kb_version, stack)
|
|
if pending:
|
|
return Check(
|
|
"kb-version", "WARN",
|
|
f"Content is at {kb_version}, machinery at {stack} - "
|
|
f"{len(pending)} migration(s) outstanding",
|
|
"Run `tools/wikitool migrate status`",
|
|
)
|
|
return Check("kb-version", "OK", f"{kb_version} (nothing outstanding up to {stack})")
|
|
return Check("kb-version", "OK", f"{kb_version}")
|
|
|
|
|
|
def run_doctor() -> list[Check]:
|
|
checks: list[Check] = [
|
|
check_python(),
|
|
check_ripgrep(),
|
|
check_author(),
|
|
check_stack_version(),
|
|
check_kb_version(),
|
|
*check_git_repo(),
|
|
check_skills(),
|
|
check_structure(),
|
|
check_personalization(),
|
|
check_environment(),
|
|
check_publish_remotes(),
|
|
check_generated_files(),
|
|
check_session_id(),
|
|
]
|
|
return checks
|
|
|
|
|
|
def doctor_command(
|
|
json_out: bool = typer.Option(False, "--json", help="Print the checks as JSON"),
|
|
):
|
|
"""Check that this instance is correctly configured: dependencies, author,
|
|
git identity/remote, published skills, structure, personalization,
|
|
generated files, and session scoping. Read-only. Exits 1 only if a check
|
|
FAILs."""
|
|
checks = run_doctor()
|
|
|
|
if json_out:
|
|
typer.echo(_json.dumps([c.__dict__ for c in checks], indent=2))
|
|
else:
|
|
for check in checks:
|
|
color = {"OK": "green", "WARN": "yellow", "FAIL": "bold red"}[check.status]
|
|
line = f"[{color}]{check.status}[/{color}] {check.name}: {check.detail}"
|
|
if check.fix and check.status != "OK":
|
|
line += f"\n fix: {check.fix}"
|
|
typer.echo(line) if False else None
|
|
from rich.console import Console
|
|
|
|
Console().print(line)
|
|
|
|
if any(check.status == "FAIL" for check in checks):
|
|
raise typer.Exit(code=1)
|