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,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,
|
||||
}
|
||||
Reference in New Issue
Block a user