feat: implement repoctl L1 core (models, schemas, validate, discover, context, init, adopt)
Adds the repository-stewardship Python package (src/stewardship) with: - JSON Schemas (Draft 2020-12) for RepositoryContract, KnowledgeBase, CatalogIndex, ContextBundle, BootstrapPlan, AdoptionAssessment/Plan/Report, user config and the repoctl-result envelope. - Safe YAML I/O, path confinement, deterministic clock and canonical-JSON hashing. - validate: schema, ID uniqueness, path safety, KDB references, freshness, secret-shaped fields, shell-string detection, and Markdown frontmatter/fence/link checks. - discover/CatalogIndex with deterministic sorting and duplicate-name detection. - describe (contract-only) and context (intent-scoped ContextBundle with budgeted materialization and --strict truncation). - init: plan-then-apply bootstrap with SHA-256 plan-hash approval, no fake domain artifacts, bundled Claude skills. - adopt: assess/plan/apply/verify overlay workflow per docs/adoption-runbook.md, preserving legacy content roots and KDB, with baseline-hash re-check and rollback. - argparse-based `repoctl` CLI with human/yaml/json output and spec exit codes. - pytest suite (39 tests) covering positive/negative fixtures, discovery, context, bootstrap and adoption (including LXD- and Antivirus-shaped legacy layouts). Managed with uv (.venv), ruff clean, mypy --strict clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Sonnet 5
parent
9a39b8a941
commit
96d4d08230
@@ -0,0 +1,3 @@
|
||||
"""Repository Stewardship protocol implementation."""
|
||||
|
||||
__version__ = "0.1.0"
|
||||
@@ -0,0 +1,396 @@
|
||||
"""`repoctl adopt`: assess -> plan -> apply -> verify for an existing repository.
|
||||
|
||||
Follows docs/adoption-runbook.md. Default strategy is `overlay`: it only adds
|
||||
stewardship metadata and never moves, deletes or renames existing files. The
|
||||
`documents-to-content-root` normalization recipe is a separate, explicitly opted-in
|
||||
path (not implemented as an automatic heuristic) and is intentionally out of scope
|
||||
for this first cut beyond structural support in the AdoptionPlan schema.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import fnmatch
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from . import gitutil, io
|
||||
from .bootstrap import BootstrapAnswers, render_agents_md, render_claude_md
|
||||
from .constants import API_VERSION
|
||||
from .validate import validate_repository
|
||||
|
||||
_COLLISION_PATHS = [
|
||||
"ops/contract.yaml",
|
||||
"kdb/kdb.yaml",
|
||||
"kdb.yaml",
|
||||
"CLAUDE.md",
|
||||
"AGENTS.md",
|
||||
".claude/skills",
|
||||
".agents/skills",
|
||||
"ops/handlers",
|
||||
"ops/template-answers.yaml",
|
||||
]
|
||||
|
||||
_SECRET_SHAPED_GLOBS = [
|
||||
"*.pem", "*.key", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa",
|
||||
".env", ".env.*", "*.env", "*password*", "*secret*", "*.pfx", "*.p12",
|
||||
]
|
||||
_SECRET_EXCLUDE_SUFFIXES = (".pub", ".schema.json", ".example")
|
||||
|
||||
_TYPE_EVIDENCE: list[tuple[str, list[str]]] = [
|
||||
("infrastructure-config", ["profiles-source", "profiles", "inventory", "stacks", "terraform", "ansible"]),
|
||||
("service-config", ["policies", "acceptance", "runbooks", "deployments"]),
|
||||
("software", ["src", "pyproject.toml", "package.json", "go.mod", "Cargo.toml"]),
|
||||
("project", ["deliverables", "docs", "decisions"]),
|
||||
]
|
||||
|
||||
|
||||
def _finding(severity: str, code: str, path: str | None = None, message: str | None = None) -> dict[str, Any]:
|
||||
item: dict[str, Any] = {"severity": severity, "code": code}
|
||||
if path:
|
||||
item["path"] = path
|
||||
if message:
|
||||
item["message"] = message
|
||||
return item
|
||||
|
||||
|
||||
def _detect_secret_shaped_paths(root: Path) -> list[tuple[str, bool]]:
|
||||
"""Return (relative_path, is_tracked) for files matching secret-shaped name patterns."""
|
||||
tracked = gitutil.tracked_files(root)
|
||||
found: list[tuple[str, bool]] = []
|
||||
for path in root.rglob("*"):
|
||||
if not path.is_file():
|
||||
continue
|
||||
if ".git" in path.parts or ".venv" in path.parts or "node_modules" in path.parts:
|
||||
continue
|
||||
name = path.name
|
||||
if name.lower().endswith(_SECRET_EXCLUDE_SUFFIXES):
|
||||
continue
|
||||
if any(fnmatch.fnmatch(name.lower(), pattern) for pattern in _SECRET_SHAPED_GLOBS):
|
||||
rel = path.relative_to(root).as_posix()
|
||||
found.append((rel, rel in tracked))
|
||||
return found
|
||||
|
||||
|
||||
def _classify_type(root: Path) -> tuple[str, str, list[str]]:
|
||||
scores: dict[str, list[str]] = {t: [] for t, _ in _TYPE_EVIDENCE}
|
||||
for repo_type, markers in _TYPE_EVIDENCE:
|
||||
for marker in markers:
|
||||
if (root / marker).exists():
|
||||
scores[repo_type].append(marker)
|
||||
ranked = sorted(scores.items(), key=lambda kv: -len(kv[1]))
|
||||
best_type, best_evidence = ranked[0]
|
||||
second_count = len(ranked[1][1]) if len(ranked) > 1 else 0
|
||||
if not best_evidence:
|
||||
return "project", "low", []
|
||||
if len(best_evidence) >= 2 and len(best_evidence) > second_count:
|
||||
confidence = "high"
|
||||
elif len(best_evidence) > second_count:
|
||||
confidence = "medium"
|
||||
else:
|
||||
confidence = "low"
|
||||
return best_type, confidence, best_evidence
|
||||
|
||||
|
||||
def assess(root: Path) -> dict[str, Any]:
|
||||
head = gitutil.head_revision(root)
|
||||
dirty = gitutil.is_dirty(root)
|
||||
|
||||
proposed_type, confidence, evidence = _classify_type(root)
|
||||
|
||||
claude_exists = (root / "CLAUDE.md").exists()
|
||||
agents_exists = (root / "AGENTS.md").exists()
|
||||
canonical_direction = "none"
|
||||
findings: list[dict[str, Any]] = []
|
||||
if claude_exists and agents_exists:
|
||||
claude_text = (root / "CLAUDE.md").read_text(encoding="utf-8", errors="ignore")
|
||||
if "AGENTS.md" in claude_text:
|
||||
canonical_direction = "claude-imports-agents"
|
||||
else:
|
||||
agents_text = (root / "AGENTS.md").read_text(encoding="utf-8", errors="ignore")
|
||||
if "CLAUDE.md" in agents_text:
|
||||
canonical_direction = "legacy-agents-to-claude"
|
||||
findings.append(_finding("warning", "ADOPT_ENTRYPOINT_DIRECTION_LEGACY", "AGENTS.md"))
|
||||
else:
|
||||
canonical_direction = "independent"
|
||||
elif claude_exists:
|
||||
canonical_direction = "claude-only"
|
||||
elif agents_exists:
|
||||
canonical_direction = "agents-only"
|
||||
|
||||
knowledge: list[dict[str, Any]] = []
|
||||
if (root / "kdb" / "kdb.yaml").exists():
|
||||
knowledge.append({"path": "kdb/kdb.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"})
|
||||
elif (root / "kdb.yaml").exists():
|
||||
knowledge.append({"path": "kdb.yaml", "format": "legacy-yaml", "action": "wrap"})
|
||||
findings.append(_finding("info", "ADOPT_KDB_LEGACY", "kdb.yaml"))
|
||||
if (root / "ops" / "knowledge.yaml").exists():
|
||||
knowledge.append({"path": "ops/knowledge.yaml", "format": "stewardship-yaml", "action": "keep-or-validate"})
|
||||
|
||||
proposed_content_roots: list[dict[str, Any]] = []
|
||||
for repo_type, markers in _TYPE_EVIDENCE:
|
||||
if repo_type != proposed_type:
|
||||
continue
|
||||
for marker in markers:
|
||||
candidate = root / marker
|
||||
if candidate.is_dir():
|
||||
proposed_content_roots.append(
|
||||
{"id": marker.replace("/", "-").lower(), "path": marker, "role": marker, "authority": "source"}
|
||||
)
|
||||
|
||||
collisions: list[str] = []
|
||||
for rel in _COLLISION_PATHS:
|
||||
if (root / rel).exists():
|
||||
collisions.append(rel)
|
||||
if (root / "kdb" / "kdb.yaml").exists() and (root / "kdb.yaml").exists():
|
||||
findings.append(_finding("warning", "ADOPT_KDB_CANONICAL_PATH_OCCUPIED", "kdb/kdb.yaml"))
|
||||
|
||||
for rel, tracked in _detect_secret_shaped_paths(root):
|
||||
if tracked:
|
||||
findings.append(_finding("error", "ADOPT_SECRET_TRACKED", rel, "Tracked path matches a secret-shaped filename pattern"))
|
||||
else:
|
||||
findings.append(_finding("info", "ADOPT_SECRET_TRACKED", rel, "Untracked secret-shaped path (path only, content not read)"))
|
||||
|
||||
if dirty:
|
||||
findings.append(_finding("warning", "ADOPT_WORKTREE_DIRTY"))
|
||||
|
||||
questions: list[str] = []
|
||||
confirmation_required = confidence != "high"
|
||||
if confirmation_required:
|
||||
questions.append("Confirm repository type and confidence evidence")
|
||||
questions.append("Confirm owner(s) and lifecycle")
|
||||
|
||||
return {
|
||||
"schema": "stewardship/adoption-assessment@0.1",
|
||||
"repository": {"path": str(root), "baselineRevision": head, "dirty": dirty},
|
||||
"classification": {
|
||||
"proposedType": proposed_type,
|
||||
"confidence": confidence,
|
||||
"evidence": evidence,
|
||||
"confirmationRequired": confirmation_required,
|
||||
},
|
||||
"entrypoints": {
|
||||
"claude": "CLAUDE.md" if claude_exists else None,
|
||||
"portable": "AGENTS.md" if agents_exists else None,
|
||||
"canonicalDirection": canonical_direction,
|
||||
},
|
||||
"knowledge": knowledge,
|
||||
"proposedContentRoots": proposed_content_roots,
|
||||
"collisions": collisions,
|
||||
"findings": findings,
|
||||
"questions": questions,
|
||||
}
|
||||
|
||||
|
||||
def build_plan(
|
||||
root: Path,
|
||||
assessment: dict[str, Any],
|
||||
*,
|
||||
confirmed_name: str,
|
||||
confirmed_title: str | None = None,
|
||||
confirmed_owners: list[str] | None = None,
|
||||
confirmed_lifecycle: str = "active",
|
||||
strategy: str = "overlay",
|
||||
) -> dict[str, Any]:
|
||||
if strategy != "overlay":
|
||||
raise ValueError("Only the overlay strategy is implemented; normalize requires an explicit recipe run")
|
||||
|
||||
baseline = assessment["repository"]["baselineRevision"]
|
||||
changes: list[dict[str, Any]] = []
|
||||
forbidden: list[str] = []
|
||||
|
||||
contract_exists = (root / "ops/contract.yaml").exists()
|
||||
content_roots = [
|
||||
{
|
||||
"id": cr["id"],
|
||||
"role": cr["role"],
|
||||
"path": cr["path"],
|
||||
"kind": "directory",
|
||||
"authority": cr.get("authority", "source"),
|
||||
"writePolicy": "managed",
|
||||
}
|
||||
for cr in assessment.get("proposedContentRoots", [])
|
||||
]
|
||||
for cr in content_roots:
|
||||
forbidden.append(f"{cr['path']}/**")
|
||||
|
||||
if not contract_exists:
|
||||
contract = {
|
||||
"apiVersion": API_VERSION,
|
||||
"kind": "RepositoryContract",
|
||||
"metadata": {
|
||||
"name": confirmed_name,
|
||||
"title": confirmed_title or confirmed_name,
|
||||
"owners": confirmed_owners or [],
|
||||
},
|
||||
"spec": {
|
||||
"summary": f"Adopted repository {confirmed_name}",
|
||||
"repository": {
|
||||
"type": assessment["classification"]["proposedType"],
|
||||
"lifecycle": confirmed_lifecycle,
|
||||
},
|
||||
"template": {
|
||||
"id": "repository." + assessment["classification"]["proposedType"].split("-")[0],
|
||||
"version": "0.1.0",
|
||||
"source": "repo:repository-stewardship",
|
||||
"mode": "adopted-overlay",
|
||||
"managedPaths": ["ops/contract.yaml"],
|
||||
},
|
||||
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
|
||||
"knowledge": {"entrypoint": _knowledge_entrypoint(assessment)},
|
||||
"contentRoots": content_roots,
|
||||
},
|
||||
}
|
||||
changes.append({"action": "create", "path": "ops/contract.yaml", "ownership": "stewardship", "content": io.yaml_text(contract)})
|
||||
else:
|
||||
changes.append({"action": "preserve", "path": "ops/contract.yaml", "ownership": "repository"})
|
||||
|
||||
kdb_entries = assessment.get("knowledge", [])
|
||||
kdb_paths = {entry["path"] for entry in kdb_entries}
|
||||
if "kdb/kdb.yaml" not in kdb_paths:
|
||||
legacy = next((e for e in kdb_entries if e["action"] == "wrap"), None)
|
||||
kdb: dict[str, Any] = {
|
||||
"apiVersion": API_VERSION,
|
||||
"kind": "KnowledgeBase",
|
||||
"metadata": {"name": f"{confirmed_name}-knowledge-index"},
|
||||
"spec": {
|
||||
"repository": f"repo:{confirmed_name}",
|
||||
"defaultLanguage": "en",
|
||||
"topics": [],
|
||||
"documents": [],
|
||||
},
|
||||
}
|
||||
target_kdb_path = "kdb/kdb.yaml"
|
||||
if legacy:
|
||||
kdb["spec"]["documents"].append(
|
||||
{
|
||||
"id": "legacy-knowledge-base",
|
||||
"title": "Existing knowledge base",
|
||||
"role": "reference",
|
||||
"path": legacy["path"],
|
||||
"mediaType": "application/yaml",
|
||||
"authority": "local-canonical",
|
||||
"status": "verified",
|
||||
}
|
||||
)
|
||||
forbidden.append(legacy["path"])
|
||||
changes.append({"action": "create", "path": target_kdb_path, "ownership": "stewardship", "reason": "Compatibility index for legacy knowledge base" if legacy else "Minimal KDB", "content": io.yaml_text(kdb)})
|
||||
else:
|
||||
changes.append({"action": "preserve", "path": "kdb/kdb.yaml", "ownership": "repository"})
|
||||
|
||||
if not (root / "AGENTS.md").exists():
|
||||
answers = BootstrapAnswers(
|
||||
name=confirmed_name, title=confirmed_title or confirmed_name, owners=confirmed_owners or [],
|
||||
repository_type=assessment["classification"]["proposedType"], lifecycle=confirmed_lifecycle,
|
||||
)
|
||||
changes.append({"action": "create", "path": "AGENTS.md", "ownership": "shared", "content": render_agents_md(answers)})
|
||||
else:
|
||||
changes.append({"action": "preserve", "path": "AGENTS.md", "ownership": "repository"})
|
||||
|
||||
if not (root / "CLAUDE.md").exists():
|
||||
changes.append({"action": "create", "path": "CLAUDE.md", "ownership": "shared", "content": render_claude_md()})
|
||||
else:
|
||||
changes.append({"action": "preserve", "path": "CLAUDE.md", "ownership": "repository"})
|
||||
|
||||
preserved_already = {c["path"] for c in changes if c["action"] == "preserve"}
|
||||
for rel in ("kdb.yaml", "profiles-source", "profiles"):
|
||||
if (root / rel).exists() and rel not in preserved_already:
|
||||
changes.append({"action": "preserve", "path": rel, "ownership": "repository"})
|
||||
preserved_already.add(rel)
|
||||
|
||||
forbidden.append(".ssh/**")
|
||||
|
||||
plan: dict[str, Any] = {
|
||||
"schema": "stewardship/adoption-plan@0.1",
|
||||
"repository": f"repo:{confirmed_name}",
|
||||
"baselineRevision": baseline,
|
||||
"strategy": strategy,
|
||||
"changes": changes,
|
||||
"forbiddenChanges": sorted(set(forbidden)),
|
||||
"validations": [
|
||||
"stewardship-schema",
|
||||
"path-confinement",
|
||||
"knowledge-references",
|
||||
"agent-entrypoint-cycle",
|
||||
],
|
||||
"approval": {"required": True},
|
||||
}
|
||||
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
||||
plan["planHash"] = plan_hash
|
||||
return plan
|
||||
|
||||
|
||||
def _knowledge_entrypoint(assessment: dict[str, Any]) -> str:
|
||||
for entry in assessment.get("knowledge", []):
|
||||
if entry["path"] == "kdb/kdb.yaml":
|
||||
return "kdb/kdb.yaml"
|
||||
return "kdb/kdb.yaml"
|
||||
|
||||
|
||||
def apply_plan(root: Path, plan: dict[str, Any], approve_hash: str) -> list[str]:
|
||||
expected_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
||||
if expected_hash != plan.get("planHash"):
|
||||
raise ValueError("Plan hash does not match plan content; re-plan before apply")
|
||||
if approve_hash != plan["planHash"]:
|
||||
raise ValueError("Approval hash does not match plan hash")
|
||||
|
||||
current_head = gitutil.head_revision(root)
|
||||
if current_head != plan["baselineRevision"]:
|
||||
raise ValueError("ADOPT_BASELINE_CHANGED: baseline revision changed since plan was built; re-plan")
|
||||
|
||||
to_write = [c for c in plan["changes"] if c["action"] in ("create", "patch-managed-block")]
|
||||
for change in to_write:
|
||||
target = root / change["path"]
|
||||
if change["action"] == "create" and target.exists():
|
||||
raise FileExistsError(f"ADOPT_PATH_COLLISION: refusing to overwrite existing path: {change['path']}")
|
||||
|
||||
written: list[str] = []
|
||||
backups: dict[str, bytes | None] = {}
|
||||
try:
|
||||
for change in to_write:
|
||||
target = root / change["path"]
|
||||
backups[change["path"]] = target.read_bytes() if target.exists() else None
|
||||
io.write_text_atomic(target, change["content"])
|
||||
written.append(change["path"])
|
||||
except Exception:
|
||||
for rel, original in backups.items():
|
||||
target = root / rel
|
||||
if original is None:
|
||||
if target.exists() and rel in written:
|
||||
target.unlink()
|
||||
else:
|
||||
target.write_bytes(original)
|
||||
raise
|
||||
return written
|
||||
|
||||
|
||||
def verify(root: Path, plan: dict[str, Any] | None = None) -> dict[str, Any]:
|
||||
validation = validate_repository(root)
|
||||
baseline = gitutil.head_revision(root)
|
||||
|
||||
changed_paths: list[str] = []
|
||||
preserved_paths: list[str] = []
|
||||
if plan is not None:
|
||||
for change in plan["changes"]:
|
||||
if change["action"] in ("create", "patch-managed-block"):
|
||||
changed_paths.append(change["path"])
|
||||
elif change["action"] == "preserve":
|
||||
preserved_paths.append(change["path"])
|
||||
|
||||
unresolved = sorted({f.code for f in validation.findings if f.severity in ("warning", "error")})
|
||||
if any(f.severity == "error" for f in validation.findings):
|
||||
outcome = "fail"
|
||||
elif unresolved:
|
||||
outcome = "pass-with-warnings"
|
||||
else:
|
||||
outcome = "pass"
|
||||
|
||||
return {
|
||||
"schema": "stewardship/adoption-report@0.1",
|
||||
"repository": f"repo:{(validation.contract or {}).get('metadata', {}).get('name', 'unknown')}",
|
||||
"baselineRevision": baseline,
|
||||
"compatibilityLevel": "L1",
|
||||
"outcome": outcome,
|
||||
"changedPaths": sorted(set(changed_paths)),
|
||||
"preservedPaths": sorted(set(preserved_paths)),
|
||||
"unresolvedFindings": unresolved,
|
||||
}
|
||||
@@ -0,0 +1,235 @@
|
||||
"""`repoctl init`: plan-then-apply bootstrap of a new repository.
|
||||
|
||||
Content roots are declared in the contract but their directories are not created —
|
||||
this repository's self-hosting rule forbids placeholder directories and fictional
|
||||
domain artifacts. `init` never commits, pushes or creates a remote.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import subprocess
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from . import io
|
||||
from .clock import DEFAULT_CLOCK
|
||||
from .constants import API_VERSION
|
||||
from .skills_content import (
|
||||
REPO_HANDOFF_SKILL,
|
||||
REPOSITORY_ADOPTION_SKILL,
|
||||
REPOSITORY_BOOTSTRAP_SKILL,
|
||||
)
|
||||
|
||||
TEMPLATE_IDS = {
|
||||
"infrastructure-config": "repository.infrastructure",
|
||||
"service-config": "repository.service",
|
||||
"software": "repository.software",
|
||||
"project": "repository.project",
|
||||
}
|
||||
|
||||
TEMPLATE_VERSION = "0.1.0"
|
||||
|
||||
_DEFAULT_CONTENT_ROOTS: dict[str, list[dict[str, str]]] = {
|
||||
"infrastructure-config": [
|
||||
{"id": "desired-state", "role": "desired", "path": "desired", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
{"id": "inventory", "role": "inventory", "path": "inventory", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
],
|
||||
"service-config": [
|
||||
{"id": "policies", "role": "policies", "path": "policies", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
{"id": "acceptance", "role": "acceptance", "path": "acceptance", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
],
|
||||
"software": [
|
||||
{"id": "source", "role": "source", "path": "src", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
{"id": "tests", "role": "tests", "path": "tests", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
],
|
||||
"project": [
|
||||
{"id": "deliverables", "role": "deliverables", "path": "deliverables", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
{"id": "decisions", "role": "decisions", "path": "decisions", "kind": "directory", "authority": "source", "writePolicy": "managed"},
|
||||
],
|
||||
}
|
||||
|
||||
SSH_RECOMMENDATION = (
|
||||
"Consider a repository-scoped SSH deploy key: read-only by default, private key kept "
|
||||
"outside Git, and scoped to only this repository. repoctl does not generate or store "
|
||||
"the key; use the gen-ssh-eddsa workflow or your Git host's deploy key feature."
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class BootstrapAnswers:
|
||||
name: str
|
||||
title: str
|
||||
owners: list[str]
|
||||
repository_type: str
|
||||
lifecycle: str = "active"
|
||||
namespace: str | None = None
|
||||
access: str | None = None
|
||||
summary: str | None = None
|
||||
content_roots: list[dict[str, str]] | None = None
|
||||
git_init: bool = False
|
||||
|
||||
@staticmethod
|
||||
def from_mapping(data: dict[str, Any]) -> BootstrapAnswers:
|
||||
return BootstrapAnswers(
|
||||
name=data["name"],
|
||||
title=data.get("title", data["name"]),
|
||||
owners=list(data.get("owners", [])),
|
||||
repository_type=data["repositoryType"],
|
||||
lifecycle=data.get("lifecycle", "active"),
|
||||
namespace=data.get("namespace"),
|
||||
access=data.get("access"),
|
||||
summary=data.get("summary"),
|
||||
content_roots=data.get("contentRoots"),
|
||||
git_init=bool(data.get("gitInit", False)),
|
||||
)
|
||||
|
||||
|
||||
def _render_contract(answers: BootstrapAnswers) -> str:
|
||||
content_roots = answers.content_roots if answers.content_roots is not None else _DEFAULT_CONTENT_ROOTS.get(answers.repository_type, [])
|
||||
contract: dict[str, Any] = {
|
||||
"apiVersion": API_VERSION,
|
||||
"kind": "RepositoryContract",
|
||||
"metadata": {
|
||||
"name": answers.name,
|
||||
"title": answers.title,
|
||||
"owners": answers.owners,
|
||||
},
|
||||
"spec": {
|
||||
"summary": answers.summary or f"{answers.title} repository",
|
||||
"repository": {
|
||||
"type": answers.repository_type,
|
||||
"lifecycle": answers.lifecycle,
|
||||
**({"namespace": answers.namespace} if answers.namespace else {}),
|
||||
**({"access": answers.access} if answers.access else {}),
|
||||
},
|
||||
"template": {
|
||||
"id": TEMPLATE_IDS[answers.repository_type],
|
||||
"version": TEMPLATE_VERSION,
|
||||
"source": "repo:repository-stewardship",
|
||||
"answersRef": "ops/template-answers.yaml",
|
||||
"mode": "generated",
|
||||
},
|
||||
"agent": {"primary": "CLAUDE.md", "portable": "AGENTS.md"},
|
||||
"knowledge": {"entrypoint": "kdb/kdb.yaml"},
|
||||
"contentRoots": content_roots,
|
||||
},
|
||||
}
|
||||
return io.yaml_text(contract)
|
||||
|
||||
|
||||
def _render_kdb(answers: BootstrapAnswers) -> str:
|
||||
kdb = {
|
||||
"apiVersion": API_VERSION,
|
||||
"kind": "KnowledgeBase",
|
||||
"metadata": {"name": f"{answers.name}-kdb", "title": f"{answers.title} knowledge base"},
|
||||
"spec": {
|
||||
"repository": f"repo:{answers.name}",
|
||||
"defaultLanguage": "en",
|
||||
"topics": [],
|
||||
"documents": [],
|
||||
},
|
||||
}
|
||||
return io.yaml_text(kdb)
|
||||
|
||||
|
||||
def render_agents_md(answers: BootstrapAnswers) -> str:
|
||||
return f"""# Repository instructions
|
||||
|
||||
## Purpose
|
||||
|
||||
{answers.summary or answers.title}
|
||||
|
||||
## Start here
|
||||
|
||||
1. Read `ops/contract.yaml` to identify the repository and authoritative content roots.
|
||||
2. Read the small index in `kdb/kdb.yaml`.
|
||||
3. Match the task to an exact topic intent.
|
||||
4. Open only the documents and headings named by that topic's `data.readHints`.
|
||||
|
||||
## Safety
|
||||
|
||||
- Do not run destructive operations without an approved plan.
|
||||
- Do not place secrets, tokens or private keys in this repository.
|
||||
- Use `repoctl validate --repo .` before proposing changes to contract or KDB.
|
||||
"""
|
||||
|
||||
|
||||
def render_claude_md() -> str:
|
||||
return """# CLAUDE.md
|
||||
|
||||
@AGENTS.md
|
||||
|
||||
## Claude-specific guidance
|
||||
|
||||
Use `repoctl context` before loading detailed knowledge or running repository operations.
|
||||
"""
|
||||
|
||||
|
||||
def _render_template_answers(answers: BootstrapAnswers) -> str:
|
||||
return io.yaml_text(
|
||||
{
|
||||
"schema": "stewardship/template-answers@0.1",
|
||||
"templateId": TEMPLATE_IDS[answers.repository_type],
|
||||
"templateVersion": TEMPLATE_VERSION,
|
||||
"name": answers.name,
|
||||
"title": answers.title,
|
||||
"owners": answers.owners,
|
||||
"repositoryType": answers.repository_type,
|
||||
"lifecycle": answers.lifecycle,
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def _render_gitignore() -> str:
|
||||
return "ops/runs/\n.venv/\n__pycache__/\n"
|
||||
|
||||
|
||||
def build_bootstrap_plan(answers: BootstrapAnswers) -> dict[str, Any]:
|
||||
contract_text = _render_contract(answers)
|
||||
files = [
|
||||
{"path": "ops/contract.yaml", "content": contract_text},
|
||||
{"path": "kdb/kdb.yaml", "content": _render_kdb(answers)},
|
||||
{"path": "AGENTS.md", "content": render_agents_md(answers)},
|
||||
{"path": "CLAUDE.md", "content": render_claude_md()},
|
||||
{"path": "ops/template-answers.yaml", "content": _render_template_answers(answers)},
|
||||
{"path": ".gitignore", "content": _render_gitignore()},
|
||||
{"path": ".claude/skills/repository-bootstrap/SKILL.md", "content": REPOSITORY_BOOTSTRAP_SKILL},
|
||||
{"path": ".claude/skills/repository-adoption/SKILL.md", "content": REPOSITORY_ADOPTION_SKILL},
|
||||
{"path": ".claude/skills/repo-handoff/SKILL.md", "content": REPO_HANDOFF_SKILL},
|
||||
]
|
||||
plan: dict[str, Any] = {
|
||||
"schema": "stewardship/bootstrap-plan@0.1",
|
||||
"repository": answers.name,
|
||||
"repositoryType": answers.repository_type,
|
||||
"createdAt": DEFAULT_CLOCK.now_iso(),
|
||||
"gitInit": answers.git_init,
|
||||
"files": files,
|
||||
"recommendations": [SSH_RECOMMENDATION],
|
||||
}
|
||||
plan_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
||||
plan["planHash"] = plan_hash
|
||||
return plan
|
||||
|
||||
|
||||
def apply_bootstrap_plan(root: Path, plan: dict[str, Any], approve_hash: str) -> list[str]:
|
||||
expected_hash = io.sha256({k: v for k, v in plan.items() if k != "planHash"})
|
||||
if expected_hash != plan.get("planHash"):
|
||||
raise ValueError("Plan hash does not match plan content; re-plan before apply")
|
||||
if approve_hash != plan["planHash"]:
|
||||
raise ValueError("Approval hash does not match plan hash")
|
||||
|
||||
written: list[str] = []
|
||||
for file_entry in plan["files"]:
|
||||
target = root / file_entry["path"]
|
||||
if target.exists():
|
||||
raise FileExistsError(f"Refusing to overwrite existing file: {file_entry['path']}")
|
||||
for file_entry in plan["files"]:
|
||||
target = root / file_entry["path"]
|
||||
io.write_text_atomic(target, file_entry["content"])
|
||||
written.append(file_entry["path"])
|
||||
|
||||
if plan.get("gitInit") and not (root / ".git").exists():
|
||||
subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
|
||||
|
||||
return written
|
||||
@@ -0,0 +1,334 @@
|
||||
"""`repoctl`: thin argparse CLI adapter over the stewardship library.
|
||||
|
||||
Exit codes (specification.md 19.2): 0 success, 1 validation/operation failure,
|
||||
2 invalid invocation/input, 3 repository not found, 4 stale/incomplete strict
|
||||
context, 5 approval required or denied.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from . import adoption, bootstrap, config, discovery, io
|
||||
from .constants import CONTRACT_PATH
|
||||
from .context import build_context
|
||||
from .paths import find_repository_root
|
||||
from .render import build_envelope, emit
|
||||
from .schema_loader import validate_against_kind
|
||||
from .types import Finding
|
||||
from .validate import validate_repository
|
||||
|
||||
EXIT_SUCCESS = 0
|
||||
EXIT_VALIDATION_FAILURE = 1
|
||||
EXIT_INVALID_INPUT = 2
|
||||
EXIT_NOT_FOUND = 3
|
||||
EXIT_STRICT_INCOMPLETE = 4
|
||||
EXIT_APPROVAL = 5
|
||||
|
||||
|
||||
class CliError(Exception):
|
||||
def __init__(self, message: str, exit_code: int = EXIT_INVALID_INPUT):
|
||||
super().__init__(message)
|
||||
self.exit_code = exit_code
|
||||
|
||||
|
||||
def _resolve_repo(repo_arg: str | None, roots: list[str] | None) -> Path:
|
||||
if repo_arg:
|
||||
candidate = Path(repo_arg).expanduser()
|
||||
if candidate.exists():
|
||||
root = find_repository_root(candidate)
|
||||
if root is None:
|
||||
raise CliError(f"No .git ancestor found for {candidate}", EXIT_NOT_FOUND)
|
||||
return root
|
||||
found, _ = discovery.discover_repositories(config.resolve_roots(roots))
|
||||
for repo in found:
|
||||
name = (repo.contract.get("metadata") or {}).get("name")
|
||||
if name == repo_arg:
|
||||
return repo.path
|
||||
raise CliError(f"Repository not found: {repo_arg}", EXIT_NOT_FOUND)
|
||||
root = find_repository_root(Path.cwd())
|
||||
if root is None:
|
||||
raise CliError("No .git ancestor found from current directory", EXIT_NOT_FOUND)
|
||||
return root
|
||||
|
||||
|
||||
def _write(envelope: dict[str, Any], output: str) -> None:
|
||||
emit(envelope, output)
|
||||
|
||||
|
||||
def cmd_config(args: argparse.Namespace) -> int:
|
||||
if args.config_action == "show":
|
||||
data = config.load_config()
|
||||
_write(build_envelope("config show", "success", data, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
if args.config_action == "add-root":
|
||||
data = config.add_root(args.path)
|
||||
_write(build_envelope("config add-root", "success", data, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
if args.config_action == "remove-root":
|
||||
data = config.remove_root(args.path)
|
||||
_write(build_envelope("config remove-root", "success", data, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
raise CliError("Unknown config action")
|
||||
|
||||
|
||||
def cmd_validate(args: argparse.Namespace) -> int:
|
||||
root = _resolve_repo(args.repo, args.root)
|
||||
result = validate_repository(root)
|
||||
outcome = "success" if result.ok else "failure"
|
||||
data = {"repository": str(root), "valid": result.ok}
|
||||
_write(build_envelope("validate", outcome, data, result.findings), args.output)
|
||||
return EXIT_SUCCESS if result.ok else EXIT_VALIDATION_FAILURE
|
||||
|
||||
|
||||
def cmd_discover(args: argparse.Namespace) -> int:
|
||||
roots = config.resolve_roots(args.root)
|
||||
catalog, findings = discovery.build_catalog_index(roots)
|
||||
has_error = any(f.severity == "error" for f in findings)
|
||||
_write(build_envelope("discover", "failure" if has_error else "success", catalog, findings), args.output)
|
||||
return EXIT_VALIDATION_FAILURE if has_error else EXIT_SUCCESS
|
||||
|
||||
|
||||
def cmd_describe(args: argparse.Namespace) -> int:
|
||||
root = _resolve_repo(args.repo, args.root)
|
||||
contract_path = root / CONTRACT_PATH
|
||||
if not contract_path.exists():
|
||||
raise CliError(f"{CONTRACT_PATH} not found under {root}", EXIT_NOT_FOUND)
|
||||
contract = io.load_yaml(contract_path)
|
||||
errors = validate_against_kind("RepositoryContract", contract) if isinstance(contract, dict) else ["not a mapping"]
|
||||
findings = [Finding("error", "CONTRACT_SCHEMA_INVALID", e) for e in errors]
|
||||
outcome = "failure" if findings else "success"
|
||||
_write(build_envelope("describe", outcome, contract, findings), args.output)
|
||||
return EXIT_VALIDATION_FAILURE if findings else EXIT_SUCCESS
|
||||
|
||||
|
||||
def cmd_context(args: argparse.Namespace) -> int:
|
||||
root = _resolve_repo(args.repo, args.root)
|
||||
result = build_context(
|
||||
root,
|
||||
args.intent,
|
||||
include_related=args.include_related,
|
||||
materialize=args.materialize,
|
||||
budget_bytes=args.budget_bytes,
|
||||
strict=args.strict,
|
||||
)
|
||||
data = dict(result.bundle)
|
||||
if result.materialized:
|
||||
data["spec"] = dict(data["spec"])
|
||||
data["spec"]["materializedContent"] = [
|
||||
{"document": m.document_id, "path": m.path, "bytes": m.bytes_used, "content": m.content}
|
||||
for m in result.materialized
|
||||
]
|
||||
findings = [
|
||||
Finding(w.split(":", 2)[0], w.split(":", 2)[1], w.split(":", 2)[2])
|
||||
for w in result.bundle["spec"]["warnings"]
|
||||
]
|
||||
outcome = "success"
|
||||
exit_code = EXIT_SUCCESS
|
||||
if result.truncated and args.strict:
|
||||
outcome = "failure"
|
||||
exit_code = EXIT_STRICT_INCOMPLETE
|
||||
_write(build_envelope("context", outcome, data, findings), args.output)
|
||||
return exit_code
|
||||
|
||||
|
||||
def cmd_init(args: argparse.Namespace) -> int:
|
||||
repo_path = Path(args.repo).expanduser()
|
||||
if args.apply:
|
||||
if not args.plan or not args.approve:
|
||||
raise CliError("--apply requires --plan and --approve", EXIT_INVALID_INPUT)
|
||||
plan = io.load_yaml(Path(args.plan))
|
||||
repo_path.mkdir(parents=True, exist_ok=True)
|
||||
try:
|
||||
written = bootstrap.apply_bootstrap_plan(repo_path, plan, args.approve)
|
||||
except ValueError as exc:
|
||||
_write(build_envelope("init apply", "failure", None, [Finding("error", "APPROVAL_FAILED", str(exc))]), args.output)
|
||||
return EXIT_APPROVAL
|
||||
except FileExistsError as exc:
|
||||
_write(build_envelope("init apply", "failure", None, [Finding("error", "ADOPT_PATH_COLLISION", str(exc))]), args.output)
|
||||
return EXIT_VALIDATION_FAILURE
|
||||
_write(build_envelope("init apply", "success", {"written": written}, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
|
||||
if args.answers:
|
||||
answers_data = io.load_yaml(Path(args.answers))
|
||||
else:
|
||||
answers_data = {}
|
||||
if args.name:
|
||||
answers_data["name"] = args.name
|
||||
if args.type:
|
||||
answers_data["repositoryType"] = args.type
|
||||
if args.title:
|
||||
answers_data["title"] = args.title
|
||||
if args.owner:
|
||||
answers_data["owners"] = list(args.owner)
|
||||
if args.lifecycle:
|
||||
answers_data["lifecycle"] = args.lifecycle
|
||||
if args.git_init:
|
||||
answers_data["gitInit"] = True
|
||||
|
||||
missing = [f for f in ("name", "repositoryType") if f not in answers_data]
|
||||
if missing:
|
||||
raise CliError(f"Missing required answers: {', '.join(missing)}", EXIT_INVALID_INPUT)
|
||||
|
||||
answers = bootstrap.BootstrapAnswers.from_mapping(answers_data)
|
||||
plan = bootstrap.build_bootstrap_plan(answers)
|
||||
_write(build_envelope("init plan", "success", plan, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
|
||||
|
||||
def cmd_adopt(args: argparse.Namespace) -> int:
|
||||
repo_path = Path(args.repo).expanduser()
|
||||
if not repo_path.exists():
|
||||
raise CliError(f"Path does not exist: {repo_path}", EXIT_NOT_FOUND)
|
||||
|
||||
if args.mode == "assess":
|
||||
result = adoption.assess(repo_path)
|
||||
findings = [
|
||||
Finding(f["severity"], f["code"], f.get("message", f["code"]), path=f.get("path"))
|
||||
for f in result["findings"]
|
||||
]
|
||||
blocker = any(f.severity == "error" for f in findings)
|
||||
_write(build_envelope("adopt assess", "failure" if blocker else "success", result, findings), args.output)
|
||||
return EXIT_VALIDATION_FAILURE if blocker else EXIT_SUCCESS
|
||||
|
||||
if args.mode == "plan":
|
||||
assessment = adoption.assess(repo_path)
|
||||
if args.answers:
|
||||
answers = io.load_yaml(Path(args.answers))
|
||||
else:
|
||||
answers = {}
|
||||
name = answers.get("name") or repo_path.name.lower()
|
||||
plan = adoption.build_plan(
|
||||
repo_path,
|
||||
assessment,
|
||||
confirmed_name=name,
|
||||
confirmed_title=answers.get("title"),
|
||||
confirmed_owners=answers.get("owners"),
|
||||
confirmed_lifecycle=answers.get("lifecycle", "active"),
|
||||
strategy=args.strategy,
|
||||
)
|
||||
_write(build_envelope("adopt plan", "success", plan, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
|
||||
if args.mode == "apply":
|
||||
if not args.plan or not args.approve:
|
||||
raise CliError("--mode apply requires --plan and --approve", EXIT_INVALID_INPUT)
|
||||
plan = io.load_yaml(Path(args.plan))
|
||||
try:
|
||||
written = adoption.apply_plan(repo_path, plan, args.approve)
|
||||
except ValueError as exc:
|
||||
code = "APPROVAL_FAILED" if "Approval" in str(exc) or "hash" in str(exc) else "ADOPT_BASELINE_CHANGED"
|
||||
_write(build_envelope("adopt apply", "failure", None, [Finding("error", code, str(exc))]), args.output)
|
||||
return EXIT_APPROVAL
|
||||
except FileExistsError as exc:
|
||||
_write(build_envelope("adopt apply", "failure", None, [Finding("error", "ADOPT_PATH_COLLISION", str(exc))]), args.output)
|
||||
return EXIT_VALIDATION_FAILURE
|
||||
_write(build_envelope("adopt apply", "success", {"written": written}, []), args.output)
|
||||
return EXIT_SUCCESS
|
||||
|
||||
if args.mode == "verify":
|
||||
verify_plan = io.load_yaml(Path(args.plan)) if args.plan else None
|
||||
report = adoption.verify(repo_path, verify_plan)
|
||||
outcome = "failure" if report["outcome"] == "fail" else "success"
|
||||
_write(build_envelope("adopt verify", outcome, report, []), args.output)
|
||||
return EXIT_VALIDATION_FAILURE if report["outcome"] == "fail" else EXIT_SUCCESS
|
||||
|
||||
raise CliError(f"Unknown adopt mode: {args.mode}", EXIT_INVALID_INPUT)
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(prog="repoctl", description="Repository Stewardship CLI")
|
||||
sub = parser.add_subparsers(dest="command", required=True)
|
||||
|
||||
def add_common(p: argparse.ArgumentParser) -> None:
|
||||
p.add_argument("--output", choices=["human", "yaml", "json"], default="human")
|
||||
|
||||
p_config = sub.add_parser("config")
|
||||
add_common(p_config)
|
||||
config_sub = p_config.add_subparsers(dest="config_action", required=True)
|
||||
config_sub.add_parser("show")
|
||||
p_add_root = config_sub.add_parser("add-root")
|
||||
p_add_root.add_argument("path")
|
||||
p_remove_root = config_sub.add_parser("remove-root")
|
||||
p_remove_root.add_argument("path")
|
||||
p_config.set_defaults(func=cmd_config)
|
||||
|
||||
p_validate = sub.add_parser("validate")
|
||||
add_common(p_validate)
|
||||
p_validate.add_argument("--repo")
|
||||
p_validate.add_argument("--root", action="append")
|
||||
p_validate.set_defaults(func=cmd_validate)
|
||||
|
||||
p_discover = sub.add_parser("discover")
|
||||
add_common(p_discover)
|
||||
p_discover.add_argument("--root", action="append")
|
||||
p_discover.set_defaults(func=cmd_discover)
|
||||
|
||||
p_describe = sub.add_parser("describe")
|
||||
add_common(p_describe)
|
||||
p_describe.add_argument("--repo")
|
||||
p_describe.add_argument("--root", action="append")
|
||||
p_describe.set_defaults(func=cmd_describe)
|
||||
|
||||
p_context = sub.add_parser("context")
|
||||
add_common(p_context)
|
||||
p_context.add_argument("--repo")
|
||||
p_context.add_argument("--root", action="append")
|
||||
p_context.add_argument("--intent", required=True)
|
||||
p_context.add_argument("--include-related", action="store_true")
|
||||
p_context.add_argument("--materialize", action="store_true")
|
||||
p_context.add_argument("--budget-bytes", type=int, default=None)
|
||||
p_context.add_argument("--strict", action="store_true")
|
||||
p_context.set_defaults(func=cmd_context)
|
||||
|
||||
p_init = sub.add_parser("init")
|
||||
add_common(p_init)
|
||||
p_init.add_argument("--repo", required=True)
|
||||
p_init.add_argument("--answers")
|
||||
p_init.add_argument("--name")
|
||||
p_init.add_argument("--type", dest="type", choices=["infrastructure-config", "service-config", "software", "project"])
|
||||
p_init.add_argument("--title")
|
||||
p_init.add_argument("--owner", action="append")
|
||||
p_init.add_argument("--lifecycle")
|
||||
p_init.add_argument("--git-init", action="store_true")
|
||||
p_init.add_argument("--no-git-init", dest="git_init", action="store_false")
|
||||
p_init.set_defaults(git_init=None)
|
||||
p_init.add_argument("--apply", action="store_true")
|
||||
p_init.add_argument("--plan")
|
||||
p_init.add_argument("--approve")
|
||||
p_init.set_defaults(func=cmd_init)
|
||||
|
||||
p_adopt = sub.add_parser("adopt")
|
||||
add_common(p_adopt)
|
||||
p_adopt.add_argument("--repo", required=True)
|
||||
p_adopt.add_argument("--mode", required=True, choices=["assess", "plan", "apply", "verify"])
|
||||
p_adopt.add_argument("--answers")
|
||||
p_adopt.add_argument("--strategy", default="overlay", choices=["overlay", "normalize"])
|
||||
p_adopt.add_argument("--recipe")
|
||||
p_adopt.add_argument("--plan")
|
||||
p_adopt.add_argument("--approve")
|
||||
p_adopt.set_defaults(func=cmd_adopt)
|
||||
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
try:
|
||||
result: int = args.func(args)
|
||||
return result
|
||||
except CliError as exc:
|
||||
print(f"ERROR: {exc}", file=sys.stderr)
|
||||
return exc.exit_code
|
||||
except Exception as exc: # noqa: BLE001 - top-level CLI safety net
|
||||
print(f"ERROR: {exc}", file=sys.stderr)
|
||||
return EXIT_VALIDATION_FAILURE
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -0,0 +1,20 @@
|
||||
"""Deterministic time source so machine output is reproducible in tests."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
from datetime import UTC, datetime
|
||||
|
||||
|
||||
class Clock:
|
||||
def now(self) -> datetime:
|
||||
override = os.environ.get("REPOCTL_CLOCK_UTC")
|
||||
if override:
|
||||
return datetime.fromisoformat(override).replace(tzinfo=UTC)
|
||||
return datetime.now(UTC)
|
||||
|
||||
def now_iso(self) -> str:
|
||||
return self.now().replace(microsecond=0).isoformat().replace("+00:00", "Z")
|
||||
|
||||
|
||||
DEFAULT_CLOCK = Clock()
|
||||
@@ -0,0 +1,75 @@
|
||||
"""User configuration: repository root list used to resolve `--repo NAME`.
|
||||
|
||||
Resolution order (per docs/PLAN.md): explicit --root flags -> REPOCTL_ROOTS env ->
|
||||
user config -> current repository as a last-resort fallback. Config is only ever
|
||||
changed by explicit `config add-root` / `config remove-root`; no hidden cache.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import platform
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from . import io
|
||||
from .constants import CONFIG_SCHEMA
|
||||
|
||||
|
||||
def config_path() -> Path:
|
||||
override = os.environ.get("REPOCTL_CONFIG_PATH")
|
||||
if override:
|
||||
return Path(override)
|
||||
if platform.system() == "Windows":
|
||||
base = os.environ.get("APPDATA")
|
||||
root = Path(base) if base else Path.home() / "AppData" / "Roaming"
|
||||
return root / "RepositoryStewardship" / "config.yaml"
|
||||
xdg = os.environ.get("XDG_CONFIG_HOME")
|
||||
root = Path(xdg) if xdg else Path.home() / ".config"
|
||||
return root / "repository-stewardship" / "config.yaml"
|
||||
|
||||
|
||||
def load_config() -> dict[str, Any]:
|
||||
path = config_path()
|
||||
if not path.exists():
|
||||
return {"schema": CONFIG_SCHEMA, "roots": []}
|
||||
data = io.load_yaml(path)
|
||||
if not isinstance(data, dict):
|
||||
raise TypeError(f"Config at {path} is not a mapping")
|
||||
data.setdefault("schema", CONFIG_SCHEMA)
|
||||
data.setdefault("roots", [])
|
||||
return data
|
||||
|
||||
|
||||
def save_config(data: dict[str, Any]) -> None:
|
||||
path = config_path()
|
||||
io.write_text_atomic(path, io.yaml_text(data))
|
||||
|
||||
|
||||
def add_root(root: str) -> dict[str, Any]:
|
||||
data = load_config()
|
||||
normalized = str(Path(root).expanduser())
|
||||
roots = list(dict.fromkeys([*data.get("roots", []), normalized]))
|
||||
data["roots"] = roots
|
||||
save_config(data)
|
||||
return data
|
||||
|
||||
|
||||
def remove_root(root: str) -> dict[str, Any]:
|
||||
data = load_config()
|
||||
normalized = str(Path(root).expanduser())
|
||||
data["roots"] = [item for item in data.get("roots", []) if item != normalized]
|
||||
save_config(data)
|
||||
return data
|
||||
|
||||
|
||||
def resolve_roots(cli_roots: list[str] | None) -> list[Path]:
|
||||
if cli_roots:
|
||||
return [Path(item).expanduser() for item in cli_roots]
|
||||
env_roots = os.environ.get("REPOCTL_ROOTS")
|
||||
if env_roots:
|
||||
return [Path(item).expanduser() for item in env_roots.split(os.pathsep) if item]
|
||||
configured = load_config().get("roots", [])
|
||||
if configured:
|
||||
return [Path(item).expanduser() for item in configured]
|
||||
return [Path.cwd()]
|
||||
@@ -0,0 +1,19 @@
|
||||
from __future__ import annotations
|
||||
|
||||
API_VERSION = "stewardship.corsus.ru/v1alpha1"
|
||||
CONTRACT_PATH = "ops/contract.yaml"
|
||||
DEFAULT_KDB_PATH = "kdb/kdb.yaml"
|
||||
CONFIG_SCHEMA = "stewardship/repoctl-config@0.1"
|
||||
RESULT_SCHEMA = "stewardship/repoctl-result@0.1"
|
||||
ID_PATTERN = r"^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$"
|
||||
REPOSITORY_TYPES = {"infrastructure-config", "service-config", "software", "project"}
|
||||
LIFECYCLES = {"production", "active", "experimental", "stub", "archive", "external"}
|
||||
ACCESS_VALUES = {"public", "internal", "restricted"}
|
||||
CONTENT_KINDS = {"directory", "file", "file-set", "manifest"}
|
||||
AUTHORITIES = {"source", "generated", "observed", "mirror", "evidence"}
|
||||
WRITE_POLICIES = {"managed", "read-only", "generated"}
|
||||
DOCUMENT_AUTHORITIES = {"vendor", "local-canonical", "observed", "derived", "manual"}
|
||||
DOCUMENT_STATUSES = {"verified", "manual", "draft", "stale"}
|
||||
DOCUMENT_ROLES = {"tutorial", "how-to", "reference", "explanation", "runbook", "vendor-source", "evidence"}
|
||||
SECRET_KEYS = {"password", "token", "privatekey", "secretvalue"}
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
"""`repoctl context`: deterministic, budgeted, intent-scoped ContextBundle selection."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from .clock import DEFAULT_CLOCK
|
||||
from .io import file_sha256
|
||||
from .validate import validate_repository
|
||||
|
||||
|
||||
@dataclass
|
||||
class MaterializedItem:
|
||||
document_id: str
|
||||
path: str
|
||||
bytes_used: int
|
||||
content: str
|
||||
|
||||
|
||||
@dataclass
|
||||
class ContextResult:
|
||||
bundle: dict[str, Any]
|
||||
materialized: list[MaterializedItem] = field(default_factory=list)
|
||||
truncated: bool = False
|
||||
|
||||
|
||||
def build_context(
|
||||
root: Path,
|
||||
intent: str,
|
||||
*,
|
||||
include_related: bool = False,
|
||||
materialize: bool = False,
|
||||
budget_bytes: int | None = None,
|
||||
strict: bool = False,
|
||||
) -> ContextResult:
|
||||
validation = validate_repository(root)
|
||||
warnings: list[str] = [f"{f.severity}:{f.code}:{f.message}" for f in validation.findings if f.severity != "info"]
|
||||
|
||||
contract = validation.contract or {}
|
||||
metadata = contract.get("metadata", {}) or {}
|
||||
spec = contract.get("spec", {}) or {}
|
||||
repo_name = metadata.get("name", "unknown")
|
||||
|
||||
contract_revision = file_sha256(root / "ops/contract.yaml") if (root / "ops/contract.yaml").exists() else None
|
||||
|
||||
operations = [
|
||||
f"operation:{repo_name}/{op.get('id')}"
|
||||
for op in spec.get("operations") or []
|
||||
if isinstance(op, dict) and intent in (op.get("intents") or [])
|
||||
]
|
||||
|
||||
content_roots = [
|
||||
cr["id"] for cr in spec.get("contentRoots") or [] if isinstance(cr, dict) and cr.get("id")
|
||||
]
|
||||
|
||||
topics_selected: list[dict[str, Any]] = []
|
||||
document_ids: list[str] = []
|
||||
kdb = validation.kdb or {}
|
||||
kdb_spec = kdb.get("spec", {}) if isinstance(kdb.get("spec"), dict) else {}
|
||||
all_topics = kdb_spec.get("topics") or []
|
||||
all_documents = {d.get("id"): d for d in (kdb_spec.get("documents") or []) if isinstance(d, dict)}
|
||||
|
||||
matched = [t for t in all_topics if isinstance(t, dict) and intent in (t.get("intents") or [])]
|
||||
matched.sort(key=lambda t: (-(t.get("priority") or 50), t.get("id") or ""))
|
||||
topics_selected.extend(matched)
|
||||
|
||||
if include_related:
|
||||
related_ids: set[str] = set()
|
||||
for topic in matched:
|
||||
related_ids.update(topic.get("relatedTopics") or [])
|
||||
for topic in all_topics:
|
||||
if isinstance(topic, dict) and topic.get("id") in related_ids:
|
||||
topics_selected.append(topic)
|
||||
|
||||
seen_docs: set[str] = set()
|
||||
for topic in topics_selected:
|
||||
for doc_id in topic.get("documents") or []:
|
||||
if doc_id in seen_docs:
|
||||
continue
|
||||
seen_docs.add(doc_id)
|
||||
document_ids.append(doc_id)
|
||||
doc = all_documents.get(doc_id)
|
||||
if doc is None:
|
||||
warnings.append(f"warning:CONTEXT_DOCUMENT_MISSING:Referenced document not found: {doc_id}")
|
||||
elif doc.get("status") == "stale":
|
||||
warnings.append(f"warning:CONTEXT_DOCUMENT_STALE:Document authored status is stale: {doc_id}")
|
||||
|
||||
topics_ref = sorted(f"topic:{repo_name}/{t.get('id')}" for t in topics_selected if t.get("id"))
|
||||
operations = sorted(set(operations))
|
||||
content_roots = sorted(set(content_roots))
|
||||
document_ids = sorted(set(document_ids))
|
||||
|
||||
bundle_name = f"{repo_name}-{intent.replace('.', '-')}"
|
||||
bundle: dict[str, Any] = {
|
||||
"apiVersion": "stewardship.corsus.ru/v1alpha1",
|
||||
"kind": "ContextBundle",
|
||||
"metadata": {"name": bundle_name},
|
||||
"spec": {
|
||||
"generatedAt": DEFAULT_CLOCK.now_iso(),
|
||||
"intent": intent,
|
||||
"repository": f"repo:{repo_name}",
|
||||
"summary": spec.get("summary", ""),
|
||||
"contentRoots": content_roots,
|
||||
"operations": operations,
|
||||
"topics": topics_ref,
|
||||
"documents": document_ids,
|
||||
"warnings": warnings,
|
||||
},
|
||||
}
|
||||
if contract_revision:
|
||||
bundle["spec"]["contractRevision"] = contract_revision
|
||||
|
||||
result = ContextResult(bundle=bundle)
|
||||
|
||||
if materialize:
|
||||
remaining = budget_bytes if budget_bytes is not None else None
|
||||
materialized_items = []
|
||||
truncated = False
|
||||
for doc_id in document_ids:
|
||||
doc = all_documents.get(doc_id)
|
||||
if not doc or not doc.get("path"):
|
||||
continue
|
||||
doc_path = root / doc["path"]
|
||||
if not doc_path.exists():
|
||||
continue
|
||||
content = doc_path.read_text(encoding="utf-8")
|
||||
content_bytes = content.encode("utf-8")
|
||||
if remaining is not None:
|
||||
if len(content_bytes) > remaining:
|
||||
truncated = True
|
||||
if remaining <= 0:
|
||||
continue
|
||||
content_bytes = content_bytes[:remaining]
|
||||
content = content_bytes.decode("utf-8", errors="ignore")
|
||||
remaining -= len(content_bytes)
|
||||
materialized_items.append(
|
||||
MaterializedItem(document_id=doc_id, path=doc["path"], bytes_used=len(content_bytes), content=content)
|
||||
)
|
||||
result.materialized = materialized_items
|
||||
result.truncated = truncated
|
||||
bundle["spec"]["materialized"] = [
|
||||
{"document": item.document_id, "path": item.path, "bytes": item.bytes_used} for item in materialized_items
|
||||
]
|
||||
if truncated:
|
||||
bundle["spec"]["warnings"].append("warning:CONTEXT_BUDGET_TRUNCATED:Materialized content truncated to fit budget")
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,151 @@
|
||||
"""`repoctl discover`: find `ops/contract.yaml` under roots and build a CatalogIndex."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Iterator
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from .clock import DEFAULT_CLOCK
|
||||
from .constants import CONTRACT_PATH
|
||||
from .io import file_sha256
|
||||
from .types import Finding, sort_findings
|
||||
from .validate import validate_repository
|
||||
|
||||
_SKIP_DIR_NAMES = {
|
||||
".git",
|
||||
".venv",
|
||||
"venv",
|
||||
"node_modules",
|
||||
"__pycache__",
|
||||
".mypy_cache",
|
||||
".pytest_cache",
|
||||
".ruff_cache",
|
||||
".tox",
|
||||
"dist",
|
||||
"build",
|
||||
".eggs",
|
||||
"site-packages",
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class DiscoveredRepository:
|
||||
path: Path
|
||||
contract: dict[str, Any]
|
||||
contract_hash: str
|
||||
|
||||
|
||||
def _iter_contract_dirs(root: Path) -> Iterator[Path]:
|
||||
root = root.resolve()
|
||||
if not root.exists():
|
||||
return
|
||||
stack = [root]
|
||||
while stack:
|
||||
current = stack.pop()
|
||||
try:
|
||||
entries = sorted(current.iterdir(), key=lambda p: p.name)
|
||||
except OSError:
|
||||
continue
|
||||
if (current / CONTRACT_PATH.split("/")[0] / CONTRACT_PATH.split("/")[1]).exists():
|
||||
yield current
|
||||
for entry in entries:
|
||||
if not entry.is_dir():
|
||||
continue
|
||||
if entry.is_symlink():
|
||||
continue
|
||||
if entry.name in _SKIP_DIR_NAMES:
|
||||
continue
|
||||
stack.append(entry)
|
||||
|
||||
|
||||
def discover_repositories(roots: list[Path]) -> tuple[list[DiscoveredRepository], list[Finding]]:
|
||||
findings: list[Finding] = []
|
||||
found: list[DiscoveredRepository] = []
|
||||
seen_paths: set[Path] = set()
|
||||
for root in roots:
|
||||
for repo_dir in _iter_contract_dirs(root):
|
||||
resolved = repo_dir.resolve()
|
||||
if resolved in seen_paths:
|
||||
continue
|
||||
seen_paths.add(resolved)
|
||||
validation = validate_repository(repo_dir)
|
||||
if validation.contract is None:
|
||||
findings.extend(validation.findings)
|
||||
continue
|
||||
findings.extend(validation.findings)
|
||||
contract_hash = file_sha256(repo_dir / CONTRACT_PATH)
|
||||
found.append(DiscoveredRepository(repo_dir, validation.contract, contract_hash))
|
||||
found.sort(key=lambda item: item.path.as_posix())
|
||||
return found, findings
|
||||
|
||||
|
||||
def build_catalog_index(roots: list[Path]) -> tuple[dict[str, Any], list[Finding]]:
|
||||
repositories, findings = discover_repositories(roots)
|
||||
|
||||
seen_names: dict[str, Path] = {}
|
||||
entries = []
|
||||
relations: list[dict[str, str]] = []
|
||||
by_name: dict[str, dict[str, Any]] = {}
|
||||
|
||||
for repo in repositories:
|
||||
metadata = repo.contract.get("metadata", {}) or {}
|
||||
name = metadata.get("name")
|
||||
spec = repo.contract.get("spec", {}) or {}
|
||||
repository_info = spec.get("repository", {}) or {}
|
||||
if not name:
|
||||
findings.append(Finding("error", "CATALOG_REPOSITORY_NAME_MISSING", "Contract has no metadata.name", path=str(repo.path)))
|
||||
continue
|
||||
if name in seen_names:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"CATALOG_DUPLICATE_REPOSITORY_NAME",
|
||||
f"Repository name {name!r} is used by both {seen_names[name]} and {repo.path}",
|
||||
resource=f"repo:{name}",
|
||||
)
|
||||
)
|
||||
continue
|
||||
seen_names[name] = repo.path
|
||||
entry = {
|
||||
"ref": f"repo:{name}",
|
||||
"path": repo.path.as_posix(),
|
||||
"type": repository_info.get("type", "unknown"),
|
||||
"lifecycle": repository_info.get("lifecycle", "unknown"),
|
||||
"contractHash": repo.contract_hash,
|
||||
}
|
||||
entries.append(entry)
|
||||
by_name[name] = repo.contract
|
||||
|
||||
for name, contract in by_name.items():
|
||||
spec = contract.get("spec", {}) or {}
|
||||
for cap in spec.get("provides") or []:
|
||||
relations.append({"from": f"repo:{name}", "type": "provides", "to": f"capability:{name}/{cap.get('id')}"})
|
||||
for req in spec.get("requires") or []:
|
||||
req_ref = f"requirement:{name}/{req.get('id')}"
|
||||
relations.append({"from": f"repo:{name}", "type": "requires", "to": req_ref})
|
||||
for other_name, other_contract in by_name.items():
|
||||
for cap in (other_contract.get("spec", {}) or {}).get("provides") or []:
|
||||
if cap.get("capability") == req.get("capability"):
|
||||
relations.append({"from": req_ref, "type": "matches", "to": f"capability:{other_name}/{cap.get('id')}"})
|
||||
for binding in spec.get("bindings") or []:
|
||||
binding_ref = f"binding:{name}/{binding.get('id')}"
|
||||
requirement_ref = binding.get("requirement", "")
|
||||
relations.append({"from": binding_ref, "type": "fulfills", "to": requirement_ref})
|
||||
|
||||
entries.sort(key=lambda e: e["ref"])
|
||||
relations.sort(key=lambda r: (r["from"], r["type"], r["to"]))
|
||||
|
||||
catalog = {
|
||||
"apiVersion": "stewardship.corsus.ru/v1alpha1",
|
||||
"kind": "CatalogIndex",
|
||||
"metadata": {"name": "local-git-catalog"},
|
||||
"spec": {
|
||||
"generatedAt": DEFAULT_CLOCK.now_iso(),
|
||||
"roots": [str(r) for r in roots],
|
||||
"repositories": entries,
|
||||
"relations": relations,
|
||||
},
|
||||
}
|
||||
return catalog, sort_findings(findings)
|
||||
@@ -0,0 +1,35 @@
|
||||
"""Minimal read-only Git helpers used by adoption assess/plan/apply/verify.
|
||||
|
||||
Adoption never commits, pushes, clones or touches remotes; these helpers only ever
|
||||
call read-only `git` subcommands, plus `git init` for `repoctl init --git-init`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def _run(args: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
|
||||
return subprocess.run(
|
||||
["git", *args], cwd=cwd, capture_output=True, text=True, check=False
|
||||
)
|
||||
|
||||
|
||||
def head_revision(root: Path) -> str:
|
||||
result = _run(["rev-parse", "HEAD"], root)
|
||||
if result.returncode != 0:
|
||||
return "unborn"
|
||||
return result.stdout.strip()
|
||||
|
||||
|
||||
def is_dirty(root: Path) -> bool:
|
||||
result = _run(["status", "--porcelain"], root)
|
||||
return bool(result.stdout.strip())
|
||||
|
||||
|
||||
def tracked_files(root: Path) -> set[str]:
|
||||
result = _run(["ls-files"], root)
|
||||
if result.returncode != 0:
|
||||
return set()
|
||||
return {line.strip() for line in result.stdout.splitlines() if line.strip()}
|
||||
@@ -0,0 +1,86 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from ruamel.yaml import YAML
|
||||
from ruamel.yaml.error import YAMLError
|
||||
|
||||
|
||||
class ResourceError(ValueError):
|
||||
"""Input cannot be safely parsed as an expected resource."""
|
||||
|
||||
|
||||
def _safe_yaml() -> YAML:
|
||||
yaml = YAML(typ="safe", pure=True)
|
||||
yaml.allow_duplicate_keys = False
|
||||
return yaml
|
||||
|
||||
|
||||
def _output_yaml() -> YAML:
|
||||
yaml = YAML()
|
||||
yaml.default_flow_style = False
|
||||
yaml.allow_unicode = True
|
||||
yaml.indent(mapping=2, sequence=4, offset=2)
|
||||
return yaml
|
||||
|
||||
|
||||
def load_yaml(path: Path) -> Any:
|
||||
try:
|
||||
with path.open("r", encoding="utf-8") as handle:
|
||||
return _safe_yaml().load(handle)
|
||||
except (OSError, YAMLError) as exc:
|
||||
raise ResourceError(f"Cannot parse YAML: {exc}") from exc
|
||||
|
||||
|
||||
def yaml_text(data: Any) -> str:
|
||||
from io import StringIO
|
||||
|
||||
stream = StringIO()
|
||||
_output_yaml().dump(data, stream)
|
||||
return stream.getvalue()
|
||||
|
||||
|
||||
def primitive(value: Any) -> Any:
|
||||
if isinstance(value, dict):
|
||||
return {str(key): primitive(item) for key, item in value.items()}
|
||||
if isinstance(value, (list, tuple)):
|
||||
return [primitive(item) for item in value]
|
||||
if hasattr(value, "isoformat") and not isinstance(value, str):
|
||||
return value.isoformat()
|
||||
return value
|
||||
|
||||
|
||||
def canonical_json(value: Any) -> str:
|
||||
return json.dumps(primitive(value), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
|
||||
|
||||
|
||||
def sha256(value: Any) -> str:
|
||||
return "sha256:" + hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def file_sha256(path: Path) -> str:
|
||||
digest = hashlib.sha256()
|
||||
with path.open("rb") as handle:
|
||||
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
|
||||
digest.update(chunk)
|
||||
return "sha256:" + digest.hexdigest()
|
||||
|
||||
|
||||
def write_text_atomic(path: Path, content: str) -> None:
|
||||
"""Write ``content`` to ``path`` via a temp file in the same directory, then replace.
|
||||
|
||||
Uses ``\\n`` line endings unconditionally so hashes and diffs are platform independent.
|
||||
"""
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
normalized = content.replace("\r\n", "\n")
|
||||
tmp = path.parent / f".{path.name}.repoctl-tmp"
|
||||
with tmp.open("w", encoding="utf-8", newline="\n") as handle:
|
||||
handle.write(normalized)
|
||||
tmp.replace(path)
|
||||
|
||||
|
||||
def dump_json(value: Any) -> str:
|
||||
return json.dumps(primitive(value), ensure_ascii=False, indent=2, sort_keys=False) + "\n"
|
||||
@@ -0,0 +1,176 @@
|
||||
"""Lightweight Markdown structural checks: frontmatter, fenced YAML/Mermaid, local links.
|
||||
|
||||
This module never executes Markdown or fetches remote resources; it is purely static.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from .io import ResourceError
|
||||
from .types import Finding
|
||||
|
||||
_FENCE_RE = re.compile(r"^(```+|~~~+)(\S*)\s*$")
|
||||
_LINK_RE = re.compile(r"(?<!!)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
|
||||
_MERMAID_HEADERS = {
|
||||
"flowchart",
|
||||
"graph",
|
||||
"sequenceDiagram",
|
||||
"stateDiagram-v2",
|
||||
"stateDiagram",
|
||||
"classDiagram",
|
||||
"erDiagram",
|
||||
"gantt",
|
||||
"pie",
|
||||
"journey",
|
||||
"mindmap",
|
||||
"timeline",
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class MarkdownCheckResult:
|
||||
findings: list[Finding]
|
||||
|
||||
|
||||
def check_markdown_file(repo_root: Path, rel_path: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
full_path = repo_root / rel_path
|
||||
try:
|
||||
text = full_path.read_text(encoding="utf-8")
|
||||
except OSError as exc:
|
||||
return [Finding("error", "MARKDOWN_UNREADABLE", str(exc), path=rel_path)]
|
||||
|
||||
findings.extend(_check_frontmatter(text, rel_path))
|
||||
findings.extend(_check_fences(text, rel_path))
|
||||
findings.extend(_check_local_links(repo_root, rel_path, text))
|
||||
return findings
|
||||
|
||||
|
||||
def _check_frontmatter(text: str, rel_path: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
if text.startswith("---\n"):
|
||||
end = text.find("\n---", 4)
|
||||
if end == -1:
|
||||
return [
|
||||
Finding(
|
||||
"error",
|
||||
"MARKDOWN_FRONTMATTER_UNTERMINATED",
|
||||
"Frontmatter block is not closed with '---'",
|
||||
path=rel_path,
|
||||
)
|
||||
]
|
||||
block = text[4:end]
|
||||
try:
|
||||
load_yaml_text(block)
|
||||
except ResourceError as exc:
|
||||
findings.append(
|
||||
Finding("error", "MARKDOWN_FRONTMATTER_INVALID_YAML", str(exc), path=rel_path)
|
||||
)
|
||||
return findings
|
||||
|
||||
|
||||
def load_yaml_text(text: str) -> Any:
|
||||
from io import StringIO
|
||||
|
||||
from ruamel.yaml import YAML
|
||||
from ruamel.yaml.error import YAMLError
|
||||
|
||||
yaml = YAML(typ="safe", pure=True)
|
||||
try:
|
||||
return yaml.load(StringIO(text))
|
||||
except YAMLError as exc:
|
||||
raise ResourceError(str(exc)) from exc
|
||||
|
||||
|
||||
def _check_fences(text: str, rel_path: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
stack: list[tuple[str, int]] = []
|
||||
lines = text.splitlines()
|
||||
fence_blocks: list[tuple[int, int, str]] = []
|
||||
for lineno, line in enumerate(lines, start=1):
|
||||
match = _FENCE_RE.match(line)
|
||||
if not match:
|
||||
continue
|
||||
marker, info = match.groups()
|
||||
if stack and stack[-1][0][0] == marker[0]:
|
||||
_open_marker, open_line = stack.pop()
|
||||
fence_blocks.append((open_line, lineno, info))
|
||||
else:
|
||||
stack.append((marker, lineno))
|
||||
for marker, lineno in stack:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"MARKDOWN_FENCE_UNBALANCED",
|
||||
f"Unclosed code fence opened at line {lineno}",
|
||||
path=rel_path,
|
||||
)
|
||||
)
|
||||
|
||||
for start, end, info in fence_blocks:
|
||||
lang = info.strip().lower()
|
||||
body = "\n".join(lines[start:end - 1])
|
||||
if lang == "yaml":
|
||||
try:
|
||||
load_yaml_text(body)
|
||||
except ResourceError as exc:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"MARKDOWN_YAML_FENCE_INVALID",
|
||||
f"Fenced YAML block at line {start} is invalid: {exc}",
|
||||
path=rel_path,
|
||||
)
|
||||
)
|
||||
elif lang == "mermaid":
|
||||
head = body.strip().splitlines()[0].strip() if body.strip() else ""
|
||||
head_token = head.split()[0] if head else ""
|
||||
if head_token not in _MERMAID_HEADERS:
|
||||
findings.append(
|
||||
Finding(
|
||||
"warning",
|
||||
"MARKDOWN_MERMAID_HEADER_UNKNOWN",
|
||||
f"Mermaid block at line {start} has an unrecognized diagram header: {head_token!r}",
|
||||
path=rel_path,
|
||||
)
|
||||
)
|
||||
return findings
|
||||
|
||||
|
||||
def _check_local_links(repo_root: Path, rel_path: str, text: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
base_dir = (repo_root / rel_path).parent
|
||||
for match in _LINK_RE.finditer(text):
|
||||
target = match.group(1)
|
||||
if target.startswith(("http://", "https://", "mailto:", "#")):
|
||||
continue
|
||||
target_path_part = target.split("#", 1)[0]
|
||||
if not target_path_part:
|
||||
continue
|
||||
candidate = (base_dir / target_path_part).resolve()
|
||||
try:
|
||||
candidate.relative_to(repo_root.resolve())
|
||||
except ValueError:
|
||||
findings.append(
|
||||
Finding(
|
||||
"warning",
|
||||
"MARKDOWN_LINK_OUTSIDE_REPOSITORY",
|
||||
f"Link target resolves outside repository root: {target}",
|
||||
path=rel_path,
|
||||
)
|
||||
)
|
||||
continue
|
||||
if not candidate.exists():
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"MARKDOWN_LINK_TARGET_MISSING",
|
||||
f"Local link target does not exist: {target}",
|
||||
path=rel_path,
|
||||
)
|
||||
)
|
||||
return findings
|
||||
@@ -0,0 +1,51 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
class PathViolation(ValueError):
|
||||
"""A resource path escapes the repository boundary."""
|
||||
|
||||
|
||||
def normalize_resource_path(value: str) -> str:
|
||||
if not value or not isinstance(value, str):
|
||||
raise PathViolation("Path must be a non-empty string")
|
||||
if "\\" in value or value.startswith(("/", "\\")) or ":" in value.split("/")[0]:
|
||||
raise PathViolation("Path must be repository-relative and use '/' separators")
|
||||
parts = value.split("/")
|
||||
if any(part in {"", ".", ".."} for part in parts):
|
||||
raise PathViolation("Path contains an unsafe segment")
|
||||
return "/".join(parts)
|
||||
|
||||
|
||||
def confined_path(root: Path, value: str, *, must_exist: bool = False) -> Path:
|
||||
normalized = normalize_resource_path(value)
|
||||
root_resolved = root.resolve(strict=True)
|
||||
candidate = root_resolved.joinpath(*normalized.split("/"))
|
||||
probe = candidate if candidate.exists() else candidate.parent
|
||||
try:
|
||||
probe.resolve(strict=True).relative_to(root_resolved)
|
||||
except ValueError as exc:
|
||||
raise PathViolation("Path resolves outside repository root") from exc
|
||||
if must_exist and not candidate.exists():
|
||||
raise PathViolation("Path does not exist")
|
||||
return candidate
|
||||
|
||||
|
||||
def find_repository_root(path: Path) -> Path | None:
|
||||
current = path.resolve()
|
||||
if current.is_file():
|
||||
current = current.parent
|
||||
for candidate in (current, *current.parents):
|
||||
if (candidate / ".git").exists():
|
||||
return candidate
|
||||
return None
|
||||
|
||||
|
||||
def display_path(path: Path) -> str:
|
||||
return path.as_posix()
|
||||
|
||||
|
||||
def split_roots(value: str) -> list[Path]:
|
||||
return [Path(item).expanduser() for item in value.split(os.pathsep) if item]
|
||||
@@ -0,0 +1,48 @@
|
||||
"""Render the `stewardship/repoctl-result@0.1` envelope as human, YAML or JSON output."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
from collections.abc import Callable
|
||||
from typing import Any
|
||||
|
||||
from .constants import RESULT_SCHEMA
|
||||
from .io import dump_json, yaml_text
|
||||
from .types import Finding
|
||||
|
||||
|
||||
def build_envelope(command: str, outcome: str, data: Any, findings: list[Finding]) -> dict[str, Any]:
|
||||
return {
|
||||
"schema": RESULT_SCHEMA,
|
||||
"command": command,
|
||||
"outcome": outcome,
|
||||
"data": data,
|
||||
"findings": [f.to_dict() for f in findings],
|
||||
}
|
||||
|
||||
|
||||
def print_findings_human(findings: list[Finding]) -> None:
|
||||
for finding in findings:
|
||||
location = f" [{finding.resource}]" if finding.resource else ""
|
||||
path = f" ({finding.path})" if finding.path else ""
|
||||
print(f"{finding.severity.upper()} {finding.code}{location}{path}: {finding.message}", file=sys.stderr)
|
||||
|
||||
|
||||
def emit(
|
||||
envelope: dict[str, Any],
|
||||
output: str,
|
||||
human_renderer: Callable[[dict[str, Any]], None] | None = None,
|
||||
) -> None:
|
||||
if output == "json":
|
||||
sys.stdout.write(dump_json(envelope))
|
||||
elif output == "yaml":
|
||||
sys.stdout.write(yaml_text(envelope))
|
||||
else:
|
||||
for finding in envelope["findings"]:
|
||||
location = f" [{finding['resource']}]" if finding.get("resource") else ""
|
||||
path = f" ({finding['path']})" if finding.get("path") else ""
|
||||
print(f"{finding['severity'].upper()} {finding['code']}{location}{path}: {finding['message']}", file=sys.stderr)
|
||||
if human_renderer is not None:
|
||||
human_renderer(envelope)
|
||||
else:
|
||||
print(f"{envelope['command']}: {envelope['outcome']}")
|
||||
@@ -0,0 +1,83 @@
|
||||
"""Load bundled JSON Schemas (Draft 2020-12) as package resources and validate resources.
|
||||
|
||||
Unknown-field rejection follows specification.md 22.2: fields prefixed with ``x-`` are an
|
||||
open extension point and MUST be preserved by consumers, so they are stripped from a
|
||||
working copy before schema validation and are never treated as "unknown normative fields".
|
||||
``metadata.annotations`` is already an open object in the schemas and needs no stripping.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from copy import deepcopy
|
||||
from functools import cache
|
||||
from importlib import resources
|
||||
from typing import Any
|
||||
|
||||
import jsonschema
|
||||
|
||||
_SCHEMA_FILES = {
|
||||
"RepositoryContract": "repository-contract.schema.json",
|
||||
"KnowledgeBase": "knowledge-base.schema.json",
|
||||
"CatalogIndex": "catalog-index.schema.json",
|
||||
"ContextBundle": "context-bundle.schema.json",
|
||||
"RepoctlResult": "result-envelope.schema.json",
|
||||
"RepoctlUserConfig": "user-config.schema.json",
|
||||
"BootstrapPlan": "bootstrap-plan.schema.json",
|
||||
"AdoptionAssessment": "adoption-assessment.schema.json",
|
||||
"AdoptionPlan": "adoption-plan.schema.json",
|
||||
"AdoptionReport": "adoption-report.schema.json",
|
||||
}
|
||||
|
||||
|
||||
class SchemaValidationError(ValueError):
|
||||
def __init__(self, errors: list[str]):
|
||||
super().__init__("; ".join(errors))
|
||||
self.errors = errors
|
||||
|
||||
|
||||
@cache
|
||||
def _load_schema(filename: str) -> dict[str, Any]:
|
||||
package = resources.files("stewardship")
|
||||
with resources.as_file(package.joinpath("schemas").joinpath(filename)) as path:
|
||||
loaded: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
|
||||
return loaded
|
||||
|
||||
|
||||
def _strip_extensions(value: Any) -> Any:
|
||||
if isinstance(value, dict):
|
||||
return {
|
||||
key: _strip_extensions(item)
|
||||
for key, item in value.items()
|
||||
if not (isinstance(key, str) and key.startswith("x-"))
|
||||
}
|
||||
if isinstance(value, list):
|
||||
return [_strip_extensions(item) for item in value]
|
||||
return value
|
||||
|
||||
|
||||
def schema_for_kind(kind: str) -> dict[str, Any]:
|
||||
filename = _SCHEMA_FILES.get(kind)
|
||||
if filename is None:
|
||||
raise KeyError(f"No bundled schema for kind {kind!r}")
|
||||
return _load_schema(filename)
|
||||
|
||||
|
||||
def validate_against_kind(kind: str, data: dict[str, Any]) -> list[str]:
|
||||
"""Return a list of human-readable schema validation error messages (empty if valid)."""
|
||||
schema = schema_for_kind(kind)
|
||||
working = _strip_extensions(deepcopy(data))
|
||||
validator_cls = jsonschema.validators.validator_for(schema)
|
||||
validator_cls.check_schema(schema)
|
||||
validator = validator_cls(schema)
|
||||
errors = []
|
||||
for error in sorted(validator.iter_errors(working), key=lambda e: list(e.absolute_path)):
|
||||
location = "/".join(str(part) for part in error.absolute_path) or "<root>"
|
||||
errors.append(f"{location}: {error.message}")
|
||||
return errors
|
||||
|
||||
|
||||
def validate_against_kind_strict(kind: str, data: dict[str, Any]) -> None:
|
||||
errors = validate_against_kind(kind, data)
|
||||
if errors:
|
||||
raise SchemaValidationError(errors)
|
||||
@@ -0,0 +1,84 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/adoption-assessment.schema.json",
|
||||
"title": "AdoptionAssessment",
|
||||
"type": "object",
|
||||
"required": ["schema", "repository", "classification", "entrypoints", "knowledge", "proposedContentRoots", "collisions", "findings", "questions"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"schema": { "const": "stewardship/adoption-assessment@0.1" },
|
||||
"repository": {
|
||||
"type": "object",
|
||||
"required": ["path", "baselineRevision", "dirty"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"path": { "type": "string" },
|
||||
"baselineRevision": { "type": "string" },
|
||||
"dirty": { "type": "boolean" }
|
||||
}
|
||||
},
|
||||
"classification": {
|
||||
"type": "object",
|
||||
"required": ["proposedType", "confidence", "evidence", "confirmationRequired"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"proposedType": { "type": "string" },
|
||||
"confidence": { "enum": ["low", "medium", "high"] },
|
||||
"evidence": { "type": "array", "items": { "type": "string" } },
|
||||
"confirmationRequired": { "type": "boolean" }
|
||||
}
|
||||
},
|
||||
"entrypoints": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"claude": { "type": ["string", "null"] },
|
||||
"portable": { "type": ["string", "null"] },
|
||||
"canonicalDirection": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"knowledge": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["path", "format", "action"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"path": { "type": "string" },
|
||||
"format": { "type": "string" },
|
||||
"action": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"proposedContentRoots": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["id", "path", "role", "authority"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"path": { "type": "string" },
|
||||
"role": { "type": "string" },
|
||||
"authority": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"collisions": { "type": "array", "items": { "type": "string" } },
|
||||
"findings": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["severity", "code"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"severity": { "enum": ["info", "warning", "error"] },
|
||||
"code": { "type": "string" },
|
||||
"path": { "type": "string" },
|
||||
"message": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"questions": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/adoption-plan.schema.json",
|
||||
"title": "AdoptionPlan",
|
||||
"type": "object",
|
||||
"required": ["schema", "repository", "baselineRevision", "strategy", "changes", "forbiddenChanges", "approval", "planHash"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"schema": { "const": "stewardship/adoption-plan@0.1" },
|
||||
"repository": { "type": "string" },
|
||||
"baselineRevision": { "type": "string" },
|
||||
"strategy": { "enum": ["overlay", "normalize"] },
|
||||
"recipe": { "type": "string" },
|
||||
"changes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["action", "path"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"action": { "enum": ["create", "patch-managed-block", "preserve", "move"] },
|
||||
"path": { "type": "string" },
|
||||
"toPath": { "type": "string" },
|
||||
"ownership": { "type": "string" },
|
||||
"reason": { "type": "string" },
|
||||
"content": { "type": "string" },
|
||||
"optional": { "type": "boolean" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"forbiddenChanges": { "type": "array", "items": { "type": "string" } },
|
||||
"validations": { "type": "array", "items": { "type": "string" } },
|
||||
"approval": {
|
||||
"type": "object",
|
||||
"required": ["required"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"required": { "type": "boolean" },
|
||||
"planHash": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"planHash": { "type": "string" }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/adoption-report.schema.json",
|
||||
"title": "AdoptionReport",
|
||||
"type": "object",
|
||||
"required": ["schema", "repository", "baselineRevision", "compatibilityLevel", "outcome", "changedPaths", "preservedPaths", "unresolvedFindings"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"schema": { "const": "stewardship/adoption-report@0.1" },
|
||||
"repository": { "type": "string" },
|
||||
"baselineRevision": { "type": "string" },
|
||||
"compatibilityLevel": { "type": "string" },
|
||||
"outcome": { "enum": ["pass", "pass-with-warnings", "fail"] },
|
||||
"changedPaths": { "type": "array", "items": { "type": "string" } },
|
||||
"preservedPaths": { "type": "array", "items": { "type": "string" } },
|
||||
"unresolvedFindings": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/bootstrap-plan.schema.json",
|
||||
"title": "BootstrapPlan",
|
||||
"type": "object",
|
||||
"required": ["schema", "repository", "files", "planHash"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"schema": { "const": "stewardship/bootstrap-plan@0.1" },
|
||||
"repository": { "type": "string" },
|
||||
"repositoryType": { "type": "string" },
|
||||
"createdAt": { "type": "string" },
|
||||
"gitInit": { "type": "boolean" },
|
||||
"files": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["path", "content"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"path": { "type": "string" },
|
||||
"content": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"recommendations": { "type": "array", "items": { "type": "string" } },
|
||||
"planHash": { "type": "string" }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/catalog-index.schema.json",
|
||||
"title": "CatalogIndex",
|
||||
"type": "object",
|
||||
"required": ["apiVersion", "kind", "metadata", "spec"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
|
||||
"kind": { "const": "CatalogIndex" },
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": { "name": { "type": "string" } }
|
||||
},
|
||||
"spec": {
|
||||
"type": "object",
|
||||
"required": ["generatedAt", "roots", "repositories", "relations"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"generatedAt": { "type": "string" },
|
||||
"roots": { "type": "array", "items": { "type": "string" } },
|
||||
"repositories": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["ref", "path", "type", "lifecycle", "contractHash"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"ref": { "type": "string" },
|
||||
"path": { "type": "string" },
|
||||
"type": { "type": "string" },
|
||||
"lifecycle": { "type": "string" },
|
||||
"contractHash": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"relations": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["from", "type", "to"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"from": { "type": "string" },
|
||||
"type": { "type": "string" },
|
||||
"to": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/context-bundle.schema.json",
|
||||
"title": "ContextBundle",
|
||||
"type": "object",
|
||||
"required": ["apiVersion", "kind", "metadata", "spec"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
|
||||
"kind": { "const": "ContextBundle" },
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": { "name": { "type": "string" } }
|
||||
},
|
||||
"spec": {
|
||||
"type": "object",
|
||||
"required": ["generatedAt", "intent", "repository", "summary", "warnings"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"generatedAt": { "type": "string" },
|
||||
"intent": { "type": "string" },
|
||||
"repository": { "type": "string" },
|
||||
"contractRevision": { "type": "string" },
|
||||
"summary": { "type": "string" },
|
||||
"contentRoots": { "type": "array", "items": { "type": "string" } },
|
||||
"operations": { "type": "array", "items": { "type": "string" } },
|
||||
"topics": { "type": "array", "items": { "type": "string" } },
|
||||
"documents": { "type": "array", "items": { "type": "string" } },
|
||||
"materialized": { "type": "array", "items": { "type": "object" } },
|
||||
"warnings": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/knowledge-base.schema.json",
|
||||
"title": "KnowledgeBase",
|
||||
"type": "object",
|
||||
"required": ["apiVersion", "kind", "metadata", "spec"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
|
||||
"kind": { "const": "KnowledgeBase" },
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"title": { "type": "string" },
|
||||
"owners": { "type": "array", "items": { "type": "string" } },
|
||||
"labels": { "type": "object", "additionalProperties": { "type": "string" } },
|
||||
"annotations": { "type": "object" }
|
||||
}
|
||||
},
|
||||
"spec": {
|
||||
"type": "object",
|
||||
"required": ["repository", "topics", "documents"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"repository": { "type": "string" },
|
||||
"defaultLanguage": { "type": "string" },
|
||||
"topics": { "type": "array", "items": { "$ref": "#/$defs/topic" } },
|
||||
"documents": { "type": "array", "items": { "$ref": "#/$defs/document" } }
|
||||
}
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"topic": {
|
||||
"type": "object",
|
||||
"required": ["id", "summary", "intents"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"title": { "type": "string" },
|
||||
"summary": { "type": "string" },
|
||||
"intents": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
|
||||
"keywords": { "type": "array", "items": { "type": "string" } },
|
||||
"priority": { "type": "integer", "minimum": 0, "maximum": 100 },
|
||||
"documents": { "type": "array", "items": { "type": "string" } },
|
||||
"relatedTopics": { "type": "array", "items": { "type": "string" } },
|
||||
"data": { "type": "object" }
|
||||
}
|
||||
},
|
||||
"document": {
|
||||
"type": "object",
|
||||
"required": ["id", "role", "authority", "status"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"title": { "type": "string" },
|
||||
"role": {
|
||||
"enum": ["tutorial", "how-to", "reference", "explanation", "runbook", "vendor-source", "evidence"]
|
||||
},
|
||||
"path": { "type": "string" },
|
||||
"uri": { "type": "string", "format": "uri" },
|
||||
"mediaType": { "type": "string" },
|
||||
"authority": { "enum": ["vendor", "local-canonical", "observed", "derived", "manual"] },
|
||||
"status": { "enum": ["verified", "manual", "draft", "stale"] },
|
||||
"provenance": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"uri": { "type": "string" },
|
||||
"vendor": { "type": "string" },
|
||||
"version": { "type": "string" },
|
||||
"retrievedAt": { "type": "string" },
|
||||
"sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
|
||||
"license": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"freshness": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"verifiedAt": { "type": "string" },
|
||||
"expiresAt": { "type": "string" },
|
||||
"verificationOperation": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,176 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/repository-contract.schema.json",
|
||||
"title": "RepositoryContract",
|
||||
"type": "object",
|
||||
"required": ["apiVersion", "kind", "metadata", "spec"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"apiVersion": { "const": "stewardship.corsus.ru/v1alpha1" },
|
||||
"kind": { "const": "RepositoryContract" },
|
||||
"metadata": { "$ref": "#/$defs/metadata" },
|
||||
"spec": {
|
||||
"type": "object",
|
||||
"required": ["summary", "repository"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"summary": { "type": "string", "minLength": 1 },
|
||||
"repository": {
|
||||
"type": "object",
|
||||
"required": ["type", "lifecycle"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"type": { "enum": ["infrastructure-config", "service-config", "software", "project"] },
|
||||
"lifecycle": { "enum": ["production", "active", "experimental", "stub", "archive", "external"] },
|
||||
"namespace": { "type": "string" },
|
||||
"access": { "enum": ["public", "internal", "restricted"] }
|
||||
}
|
||||
},
|
||||
"template": {
|
||||
"type": "object",
|
||||
"required": ["id", "version"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string" },
|
||||
"version": { "type": "string" },
|
||||
"source": { "type": "string" },
|
||||
"revision": { "type": "string" },
|
||||
"answersRef": { "type": "string" },
|
||||
"mode": { "enum": ["generated", "adopted-overlay"] },
|
||||
"managedPaths": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"agent": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"primary": { "type": "string" },
|
||||
"portable": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"knowledge": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"entrypoint": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"contentRoots": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/contentRoot" }
|
||||
},
|
||||
"provides": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/capability" }
|
||||
},
|
||||
"requires": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/requirement" }
|
||||
},
|
||||
"bindings": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/binding" }
|
||||
},
|
||||
"operations": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/operation" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"required": ["name"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"name": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"title": { "type": "string" },
|
||||
"owners": { "type": "array", "items": { "type": "string" } },
|
||||
"labels": { "type": "object", "additionalProperties": { "type": "string" } },
|
||||
"annotations": { "type": "object" }
|
||||
}
|
||||
},
|
||||
"contentRoot": {
|
||||
"type": "object",
|
||||
"required": ["id", "role", "path", "kind", "authority"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"role": { "type": "string" },
|
||||
"path": { "type": "string" },
|
||||
"kind": { "enum": ["directory", "file", "file-set", "manifest"] },
|
||||
"authority": { "enum": ["source", "generated", "observed", "mirror", "evidence"] },
|
||||
"writePolicy": { "enum": ["managed", "read-only", "generated"] },
|
||||
"selector": { "type": "string" },
|
||||
"format": { "type": "string" },
|
||||
"environments": { "type": "array", "items": { "type": "string" } },
|
||||
"generatedFrom": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"capability": {
|
||||
"type": "object",
|
||||
"required": ["id", "capability"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"capability": { "type": "string" },
|
||||
"summary": { "type": "string" },
|
||||
"parametersSchema": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"requirement": {
|
||||
"type": "object",
|
||||
"required": ["id", "capability"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"capability": { "type": "string" },
|
||||
"summary": { "type": "string" },
|
||||
"constraints": { "type": "object" },
|
||||
"preferredProviders": { "type": "array", "items": { "type": "string" } },
|
||||
"acceptance": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"binding": {
|
||||
"type": "object",
|
||||
"required": ["id", "requirement", "target", "status"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"requirement": { "type": "string" },
|
||||
"target": { "type": "string" },
|
||||
"status": { "enum": ["proposed", "active", "failed", "retired"] },
|
||||
"evidenceRef": { "type": "string" }
|
||||
}
|
||||
},
|
||||
"operation": {
|
||||
"type": "object",
|
||||
"required": ["id", "phase", "effect", "risk"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" },
|
||||
"title": { "type": "string" },
|
||||
"intents": { "type": "array", "items": { "type": "string" } },
|
||||
"phase": {
|
||||
"enum": ["describe", "inspect", "snapshot", "validate", "diff", "plan", "apply", "verify", "reconcile", "rollback"]
|
||||
},
|
||||
"effect": { "enum": ["read-only", "local-write", "external-write", "disruptive", "destructive"] },
|
||||
"risk": { "enum": ["low", "medium", "high", "critical"] },
|
||||
"execution": {
|
||||
"type": "object",
|
||||
"required": ["handler"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"handler": { "type": "string" },
|
||||
"argv": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"inputSchema": { "type": "string" },
|
||||
"outputSchema": { "type": "string" },
|
||||
"preconditions": { "type": "array", "items": { "type": "string" } },
|
||||
"approval": { "enum": ["never", "on-write", "always"] }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/repoctl-result.schema.json",
|
||||
"title": "RepoctlResult",
|
||||
"type": "object",
|
||||
"required": ["schema", "command", "outcome", "data", "findings"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"schema": { "const": "stewardship/repoctl-result@0.1" },
|
||||
"command": { "type": "string" },
|
||||
"outcome": { "enum": ["success", "failure"] },
|
||||
"data": {},
|
||||
"findings": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": ["severity", "code", "message"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"severity": { "enum": ["info", "warning", "error"] },
|
||||
"code": { "type": "string" },
|
||||
"message": { "type": "string" },
|
||||
"resource": { "type": "string" },
|
||||
"path": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://stewardship.corsus.ru/schemas/v1alpha1/repoctl-config.schema.json",
|
||||
"title": "RepoctlUserConfig",
|
||||
"type": "object",
|
||||
"required": ["schema"],
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"schema": { "const": "stewardship/repoctl-config@0.1" },
|
||||
"roots": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
"""Shared text for the three Claude project skills that ship with every bootstrap.
|
||||
|
||||
Skills are thin wrappers: they call `repoctl` with machine output and explain findings.
|
||||
They must never duplicate repoctl's classification, generation or validation logic.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
REPOSITORY_BOOTSTRAP_SKILL = """---
|
||||
name: repository-bootstrap
|
||||
description: Bootstrap a new repository into Repository Stewardship using repoctl init. Use when creating a new repository or scaffolding ops/contract.yaml, kdb/kdb.yaml and agent entrypoints from scratch.
|
||||
---
|
||||
|
||||
# repository-bootstrap
|
||||
|
||||
Thin wrapper around `repoctl init`. Do not reimplement classification, template
|
||||
rendering or validation here — call the CLI and explain its output.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Collect the missing decisions from the user: repository type
|
||||
(`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`,
|
||||
`title`, `owners`, `lifecycle`.
|
||||
2. Run `repoctl init --repo <path> --answers <answers-file> --output json` to obtain a
|
||||
`BootstrapPlan` (this performs no writes).
|
||||
3. Show the user the planned files and the `planHash`.
|
||||
4. Only after explicit approval, run
|
||||
`repoctl init --repo <path> --apply --plan <plan-file> --approve <planHash>`.
|
||||
5. Report the resulting `repoctl validate --repo <path>` findings.
|
||||
|
||||
Never invent files outside the plan and never skip the approval step.
|
||||
"""
|
||||
|
||||
REPOSITORY_ADOPTION_SKILL = """---
|
||||
name: repository-adoption
|
||||
description: Assess and adopt an existing repository into Repository Stewardship using repoctl adopt. Use when connecting an existing, non-templated repository without moving its domain content.
|
||||
---
|
||||
|
||||
# repository-adoption
|
||||
|
||||
Thin wrapper around `repoctl adopt`. The canonical procedure is
|
||||
`docs/adoption-runbook.md`; this skill only collects missing decisions, calls the CLI
|
||||
with machine output, and explains findings. It must not duplicate the runbook logic.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Run `repoctl adopt --repo <path> --mode assess --output json` (read-only).
|
||||
2. Present the classification, detected content roots, and any `questions` that need
|
||||
owner confirmation.
|
||||
3. Run `repoctl adopt --repo <path> --mode plan --output json` once open questions are
|
||||
resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`.
|
||||
4. Show the full plan (files created, patched managed blocks, preserved paths,
|
||||
forbidden changes) before asking for approval.
|
||||
5. Only after explicit approval, run
|
||||
`repoctl adopt --repo <path> --mode apply --plan <plan-file> --approve <planHash>`.
|
||||
6. Run `repoctl adopt --repo <path> --mode verify --output json` and report the
|
||||
`AdoptionReport`, including any `unresolvedFindings`.
|
||||
|
||||
Default strategy is `overlay`. Only use `--strategy normalize --recipe
|
||||
documents-to-content-root` when the owner explicitly asks to reorganize root documents.
|
||||
"""
|
||||
|
||||
REPO_HANDOFF_SKILL = """---
|
||||
name: repo-handoff
|
||||
description: Produce a minimal, intent-scoped context handoff for a repository using repoctl context. Use when another agent, session or teammate needs just enough context to work on one task in a repository.
|
||||
---
|
||||
|
||||
# repo-handoff
|
||||
|
||||
Thin wrapper around `repoctl context`. Do not read the full repository or the full KDB
|
||||
by hand when this skill applies — let `repoctl` perform the selection.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Turn the user's request into an `intent` id (e.g. `container.deploy`,
|
||||
`repository.adopt`), not a literal command.
|
||||
2. Run `repoctl context --repo <name-or-path> --intent <intent> --output json`.
|
||||
3. If the bundle looks incomplete, retry with `--include-related` or `--materialize`
|
||||
and an explicit `--budget-bytes`.
|
||||
4. Hand the resulting `ContextBundle` (and any `warnings`) to the requester instead of
|
||||
pasting raw repository files.
|
||||
"""
|
||||
@@ -0,0 +1,24 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import asdict, dataclass
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Finding:
|
||||
severity: str
|
||||
code: str
|
||||
message: str
|
||||
resource: str | None = None
|
||||
path: str | None = None
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {key: value for key, value in asdict(self).items() if value is not None}
|
||||
|
||||
|
||||
def sort_findings(findings: list[Finding]) -> list[Finding]:
|
||||
rank = {"error": 0, "warning": 1, "info": 2}
|
||||
return sorted(
|
||||
findings,
|
||||
key=lambda item: (rank.get(item.severity, 9), item.resource or "", item.path or "", item.code),
|
||||
)
|
||||
@@ -0,0 +1,416 @@
|
||||
"""`repoctl validate`: schema, path-safety, reference and Markdown checks for one repository."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import fnmatch
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from . import markdown
|
||||
from .clock import DEFAULT_CLOCK
|
||||
from .constants import CONTRACT_PATH, ID_PATTERN, SECRET_KEYS
|
||||
from .io import ResourceError, load_yaml
|
||||
from .paths import PathViolation, confined_path, normalize_resource_path
|
||||
from .schema_loader import validate_against_kind
|
||||
from .types import Finding, sort_findings
|
||||
|
||||
_ID_RE = re.compile(ID_PATTERN)
|
||||
_SHELL_CHARS = set("|&;<>$`\n\r")
|
||||
|
||||
|
||||
@dataclass
|
||||
class RepositoryValidation:
|
||||
root: Path
|
||||
contract: dict[str, Any] | None
|
||||
kdb: dict[str, Any] | None
|
||||
findings: list[Finding]
|
||||
|
||||
@property
|
||||
def ok(self) -> bool:
|
||||
return not any(item.severity == "error" for item in self.findings)
|
||||
|
||||
|
||||
def validate_repository(root: Path) -> RepositoryValidation:
|
||||
findings: list[Finding] = []
|
||||
contract_path = root / CONTRACT_PATH
|
||||
contract: dict[str, Any] | None = None
|
||||
kdb: dict[str, Any] | None = None
|
||||
|
||||
if not contract_path.exists():
|
||||
findings.append(
|
||||
Finding("error", "CONTRACT_MISSING", f"{CONTRACT_PATH} does not exist")
|
||||
)
|
||||
return RepositoryValidation(root, None, None, sort_findings(findings))
|
||||
|
||||
try:
|
||||
contract = load_yaml(contract_path)
|
||||
except ResourceError as exc:
|
||||
findings.append(Finding("error", "CONTRACT_PARSE_ERROR", str(exc), path=CONTRACT_PATH))
|
||||
return RepositoryValidation(root, None, None, sort_findings(findings))
|
||||
|
||||
if not isinstance(contract, dict):
|
||||
findings.append(
|
||||
Finding("error", "CONTRACT_NOT_MAPPING", "Contract root must be a mapping", path=CONTRACT_PATH)
|
||||
)
|
||||
return RepositoryValidation(root, None, None, sort_findings(findings))
|
||||
|
||||
resource_name = f"repo:{contract.get('metadata', {}).get('name', '?')}"
|
||||
|
||||
if contract.get("apiVersion") != "stewardship.corsus.ru/v1alpha1":
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"CONTRACT_API_VERSION_UNKNOWN",
|
||||
f"Unknown or missing apiVersion: {contract.get('apiVersion')!r}",
|
||||
resource=resource_name,
|
||||
path="apiVersion",
|
||||
)
|
||||
)
|
||||
if contract.get("kind") != "RepositoryContract":
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"CONTRACT_KIND_UNEXPECTED",
|
||||
f"Expected kind RepositoryContract, found {contract.get('kind')!r}",
|
||||
resource=resource_name,
|
||||
path="kind",
|
||||
)
|
||||
)
|
||||
|
||||
for message in validate_against_kind("RepositoryContract", contract):
|
||||
findings.append(
|
||||
Finding("error", "CONTRACT_SCHEMA_INVALID", message, resource=resource_name, path=message.split(":", 1)[0])
|
||||
)
|
||||
|
||||
spec = contract.get("spec", {}) if isinstance(contract.get("spec"), dict) else {}
|
||||
|
||||
findings.extend(_check_ids(spec, resource_name))
|
||||
findings.extend(_check_content_root_paths(root, spec, resource_name))
|
||||
findings.extend(_check_operations(root, spec, resource_name))
|
||||
findings.extend(_check_secrets(contract, resource_name, "contract"))
|
||||
|
||||
kdb_rel = None
|
||||
knowledge = spec.get("knowledge") if isinstance(spec.get("knowledge"), dict) else None
|
||||
if knowledge and knowledge.get("entrypoint"):
|
||||
kdb_rel = knowledge["entrypoint"]
|
||||
lifecycle = (spec.get("repository") or {}).get("lifecycle")
|
||||
try:
|
||||
kdb_path = confined_path(root, kdb_rel)
|
||||
except PathViolation as exc:
|
||||
findings.append(
|
||||
Finding("error", "CONTRACT_PATH_OUTSIDE_REPOSITORY", str(exc), resource=resource_name, path="spec.knowledge.entrypoint")
|
||||
)
|
||||
kdb_path = None
|
||||
if kdb_path is not None:
|
||||
if not kdb_path.exists():
|
||||
if lifecycle != "stub":
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"KNOWLEDGE_ENTRYPOINT_MISSING",
|
||||
f"KDB entrypoint does not exist: {kdb_rel}",
|
||||
resource=resource_name,
|
||||
path="spec.knowledge.entrypoint",
|
||||
)
|
||||
)
|
||||
else:
|
||||
kdb, kdb_findings = _validate_kdb(root, kdb_path, kdb_rel, resource_name)
|
||||
findings.extend(kdb_findings)
|
||||
|
||||
for entry_field, entry_path in (("primary", "agent.primary"), ("portable", "agent.portable")):
|
||||
agent_raw = spec.get("agent")
|
||||
agent: dict[str, Any] = agent_raw if isinstance(agent_raw, dict) else {}
|
||||
rel = agent.get(entry_field)
|
||||
if rel:
|
||||
full = root / rel
|
||||
if not full.exists():
|
||||
findings.append(
|
||||
Finding("warning", "AGENT_ENTRYPOINT_MISSING", f"{rel} does not exist", resource=resource_name, path=f"spec.{entry_path}")
|
||||
)
|
||||
elif full.suffix.lower() == ".md":
|
||||
findings.extend(markdown.check_markdown_file(root, rel))
|
||||
|
||||
for extra in ("README.md",):
|
||||
if (root / extra).exists():
|
||||
findings.extend(markdown.check_markdown_file(root, extra))
|
||||
|
||||
return RepositoryValidation(root, contract, kdb, sort_findings(findings))
|
||||
|
||||
|
||||
def _check_ids(spec: dict[str, Any], resource_name: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
for collection_name in ("contentRoots", "provides", "requires", "bindings", "operations"):
|
||||
items = spec.get(collection_name)
|
||||
if not isinstance(items, list):
|
||||
continue
|
||||
seen: set[str] = set()
|
||||
for item in items:
|
||||
if not isinstance(item, dict):
|
||||
continue
|
||||
item_id = item.get("id")
|
||||
if not isinstance(item_id, str) or not _ID_RE.match(item_id):
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"ID_FORMAT_INVALID",
|
||||
f"Invalid id in {collection_name}: {item_id!r}",
|
||||
resource=resource_name,
|
||||
path=f"spec.{collection_name}",
|
||||
)
|
||||
)
|
||||
continue
|
||||
if item_id in seen:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"ID_DUPLICATE",
|
||||
f"Duplicate id {item_id!r} in {collection_name}",
|
||||
resource=resource_name,
|
||||
path=f"spec.{collection_name}",
|
||||
)
|
||||
)
|
||||
seen.add(item_id)
|
||||
return findings
|
||||
|
||||
|
||||
def _check_content_root_paths(root: Path, spec: dict[str, Any], resource_name: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
lifecycle = (spec.get("repository") or {}).get("lifecycle")
|
||||
for index, item in enumerate(spec.get("contentRoots") or []):
|
||||
if not isinstance(item, dict):
|
||||
continue
|
||||
raw_path = item.get("path")
|
||||
try:
|
||||
confined = confined_path(root, raw_path) if isinstance(raw_path, str) else None
|
||||
except PathViolation as exc:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"CONTRACT_PATH_OUTSIDE_REPOSITORY",
|
||||
str(exc),
|
||||
resource=resource_name,
|
||||
path=f"spec.contentRoots[{index}].path",
|
||||
)
|
||||
)
|
||||
continue
|
||||
if confined is not None and not confined.exists() and lifecycle != "stub":
|
||||
findings.append(
|
||||
Finding(
|
||||
"warning",
|
||||
"CONTENT_ROOT_PATH_MISSING",
|
||||
f"contentRoots[{index}] path does not exist: {raw_path}",
|
||||
resource=resource_name,
|
||||
path=f"spec.contentRoots[{index}].path",
|
||||
)
|
||||
)
|
||||
return findings
|
||||
|
||||
|
||||
def _check_operations(root: Path, spec: dict[str, Any], resource_name: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
for index, op in enumerate(spec.get("operations") or []):
|
||||
if not isinstance(op, dict):
|
||||
continue
|
||||
execution = op.get("execution")
|
||||
if not isinstance(execution, dict):
|
||||
continue
|
||||
handler = execution.get("handler")
|
||||
if isinstance(handler, str):
|
||||
try:
|
||||
normalize_resource_path(handler)
|
||||
except PathViolation as exc:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"OPERATION_HANDLER_PATH_UNSAFE",
|
||||
str(exc),
|
||||
resource=resource_name,
|
||||
path=f"spec.operations[{index}].execution.handler",
|
||||
)
|
||||
)
|
||||
if any(ch in _SHELL_CHARS for ch in handler):
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"OPERATION_HANDLER_SHELL_STRING",
|
||||
"Handler path must not contain shell metacharacters",
|
||||
resource=resource_name,
|
||||
path=f"spec.operations[{index}].execution.handler",
|
||||
)
|
||||
)
|
||||
for token in execution.get("argv") or []:
|
||||
if isinstance(token, str) and any(ch in _SHELL_CHARS for ch in token):
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"OPERATION_ARGV_SHELL_STRING",
|
||||
f"argv token looks like a shell string: {token!r}",
|
||||
resource=resource_name,
|
||||
path=f"spec.operations[{index}].execution.argv",
|
||||
)
|
||||
)
|
||||
return findings
|
||||
|
||||
|
||||
def _check_secrets(data: Any, resource_name: str, top_path: str) -> list[Finding]:
|
||||
findings: list[Finding] = []
|
||||
|
||||
def walk(value: Any, path: str) -> None:
|
||||
if isinstance(value, dict):
|
||||
for key, item in value.items():
|
||||
key_norm = str(key).lower().replace("_", "").replace("-", "")
|
||||
if key_norm in SECRET_KEYS and isinstance(item, str) and item.strip():
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"SECRET_SHAPED_FIELD",
|
||||
f"Field looks like a secret value: {key}",
|
||||
resource=resource_name,
|
||||
path=f"{path}.{key}" if path else str(key),
|
||||
)
|
||||
)
|
||||
continue
|
||||
walk(item, f"{path}.{key}" if path else str(key))
|
||||
elif isinstance(value, list):
|
||||
for i, item in enumerate(value):
|
||||
walk(item, f"{path}[{i}]")
|
||||
|
||||
walk(data, top_path)
|
||||
return findings
|
||||
|
||||
|
||||
def _validate_kdb(
|
||||
root: Path, kdb_path: Path, kdb_rel: str, contract_resource: str
|
||||
) -> tuple[dict[str, Any] | None, list[Finding]]:
|
||||
findings: list[Finding] = []
|
||||
try:
|
||||
kdb = load_yaml(kdb_path)
|
||||
except ResourceError as exc:
|
||||
return None, [Finding("error", "KNOWLEDGE_PARSE_ERROR", str(exc), path=kdb_rel)]
|
||||
if not isinstance(kdb, dict):
|
||||
return None, [Finding("error", "KNOWLEDGE_NOT_MAPPING", "KDB root must be a mapping", path=kdb_rel)]
|
||||
|
||||
kdb_resource = f"repo:{kdb.get('spec', {}).get('repository', '?')}"
|
||||
|
||||
if kdb.get("kind") != "KnowledgeBase":
|
||||
findings.append(Finding("error", "KNOWLEDGE_KIND_UNEXPECTED", f"Expected kind KnowledgeBase, found {kdb.get('kind')!r}", resource=kdb_resource, path=kdb_rel))
|
||||
|
||||
for message in validate_against_kind("KnowledgeBase", kdb):
|
||||
findings.append(Finding("error", "KNOWLEDGE_SCHEMA_INVALID", message, resource=kdb_resource, path=kdb_rel))
|
||||
|
||||
kdb_spec = kdb.get("spec", {}) if isinstance(kdb.get("spec"), dict) else {}
|
||||
topics = kdb_spec.get("topics") or []
|
||||
documents = kdb_spec.get("documents") or []
|
||||
|
||||
topic_ids: set[Any] = {t.get("id") for t in topics if isinstance(t, dict)}
|
||||
doc_ids: dict[Any, dict[str, Any]] = {d.get("id"): d for d in documents if isinstance(d, dict)}
|
||||
|
||||
seen_topic_ids: set[Any] = set()
|
||||
for topic in topics:
|
||||
if not isinstance(topic, dict):
|
||||
continue
|
||||
tid = topic.get("id")
|
||||
if tid in seen_topic_ids:
|
||||
findings.append(Finding("error", "ID_DUPLICATE", f"Duplicate topic id {tid!r}", resource=kdb_resource, path=kdb_rel))
|
||||
seen_topic_ids.add(tid)
|
||||
for doc_id in topic.get("documents") or []:
|
||||
if doc_id not in doc_ids:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"KNOWLEDGE_TOPIC_DOCUMENT_MISSING",
|
||||
f"Topic {tid!r} references unknown document {doc_id!r}",
|
||||
resource=kdb_resource,
|
||||
path=kdb_rel,
|
||||
)
|
||||
)
|
||||
for related in topic.get("relatedTopics") or []:
|
||||
if related not in topic_ids:
|
||||
findings.append(
|
||||
Finding(
|
||||
"warning",
|
||||
"KNOWLEDGE_RELATED_TOPIC_MISSING",
|
||||
f"Topic {tid!r} references unknown relatedTopic {related!r}",
|
||||
resource=kdb_resource,
|
||||
path=kdb_rel,
|
||||
)
|
||||
)
|
||||
|
||||
seen_doc_ids: set[Any] = set()
|
||||
for doc in documents:
|
||||
if not isinstance(doc, dict):
|
||||
continue
|
||||
did = doc.get("id")
|
||||
if did in seen_doc_ids:
|
||||
findings.append(Finding("error", "ID_DUPLICATE", f"Duplicate document id {did!r}", resource=kdb_resource, path=kdb_rel))
|
||||
seen_doc_ids.add(did)
|
||||
has_path = bool(doc.get("path"))
|
||||
has_uri = bool(doc.get("uri"))
|
||||
if has_path == has_uri:
|
||||
findings.append(
|
||||
Finding(
|
||||
"error",
|
||||
"KNOWLEDGE_DOCUMENT_PATH_XOR_URI",
|
||||
f"Document {did!r} must set exactly one of path/uri",
|
||||
resource=kdb_resource,
|
||||
path=kdb_rel,
|
||||
)
|
||||
)
|
||||
if has_path:
|
||||
doc_path = doc["path"]
|
||||
try:
|
||||
confined = confined_path(root, doc_path)
|
||||
except PathViolation as exc:
|
||||
findings.append(Finding("error", "CONTRACT_PATH_OUTSIDE_REPOSITORY", str(exc), resource=kdb_resource, path=kdb_rel))
|
||||
confined = None
|
||||
if confined is not None:
|
||||
if not confined.exists():
|
||||
findings.append(
|
||||
Finding("error", "KNOWLEDGE_DOCUMENT_PATH_MISSING", f"Document {did!r} path does not exist: {doc_path}", resource=kdb_resource, path=kdb_rel)
|
||||
)
|
||||
elif confined.suffix.lower() == ".md":
|
||||
findings.extend(markdown.check_markdown_file(root, doc_path))
|
||||
|
||||
freshness = doc.get("freshness") if isinstance(doc.get("freshness"), dict) else None
|
||||
if freshness and freshness.get("expiresAt"):
|
||||
try:
|
||||
expires = _parse_dt(freshness["expiresAt"])
|
||||
if expires <= DEFAULT_CLOCK.now():
|
||||
findings.append(
|
||||
Finding(
|
||||
"warning",
|
||||
"KNOWLEDGE_DOCUMENT_STALE",
|
||||
f"Document {did!r} freshness expired at {freshness['expiresAt']}",
|
||||
resource=kdb_resource,
|
||||
path=kdb_rel,
|
||||
)
|
||||
)
|
||||
except ValueError:
|
||||
findings.append(
|
||||
Finding("warning", "KNOWLEDGE_FRESHNESS_UNPARSEABLE", f"Cannot parse expiresAt for document {did!r}", resource=kdb_resource, path=kdb_rel)
|
||||
)
|
||||
provenance = doc.get("provenance") if isinstance(doc.get("provenance"), dict) else None
|
||||
if provenance and provenance.get("sha256") and not re.fullmatch(r"[0-9a-f]{64}", provenance["sha256"]):
|
||||
findings.append(
|
||||
Finding("error", "KNOWLEDGE_PROVENANCE_HASH_INVALID", f"Document {did!r} sha256 must be 64 lowercase hex chars", resource=kdb_resource, path=kdb_rel)
|
||||
)
|
||||
|
||||
findings.extend(_check_secrets(kdb, kdb_resource, kdb_rel))
|
||||
return kdb, findings
|
||||
|
||||
|
||||
def _parse_dt(value: str) -> datetime:
|
||||
text = value.replace("Z", "+00:00")
|
||||
dt = datetime.fromisoformat(text)
|
||||
if dt.tzinfo is None:
|
||||
dt = dt.replace(tzinfo=UTC)
|
||||
return dt
|
||||
|
||||
|
||||
def content_root_files(root: Path, selector_root: Path, selector: str | None) -> list[Path]:
|
||||
if selector is None:
|
||||
return [selector_root] if selector_root.is_file() else list(selector_root.rglob("*"))
|
||||
return [p for p in selector_root.rglob("*") if p.is_file() and fnmatch.fnmatch(p.relative_to(selector_root).as_posix(), selector)]
|
||||
Reference in New Issue
Block a user