Files
repoctl/src/stewardship/bootstrap.py
T
Alexander BaranovandClaude Sonnet 5 64e6c2f5f5 fix: force UTF-8 stdout/stderr in repoctl and drop non-ASCII em dashes
End-to-end smoke testing of `init` and `adopt` (plan -> approve -> apply -> verify)
via subprocess surfaced a real portability bug: on Windows, sys.stdout defaults to
the console codepage rather than UTF-8 when not attached to a UTF-8 terminal, so
machine YAML/JSON output containing non-ASCII characters (an em dash in generated
skill/docstring text) could fail to decode for downstream consumers. repoctl now
reconfigures stdout/stderr to UTF-8 unconditionally in main(), and the offending
em dashes are replaced with ASCII hyphens so generated file content is unaffected
either way.

Verified via manual CLI smoke tests: full init and adopt flows (including baseline
re-check, plan-hash approval, collision rejection on re-apply, and preservation of
profiles-source/, profiles/ and legacy kdb.yaml) work end to end.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-24 15:04:11 +03:00

236 lines
8.7 KiB
Python

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