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