csh/tsl-devkit
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge commit '3d83740f88b6aaba6962256be517656496b83f25' into lsp-server

Browse Source
This commit is contained in:
csh
2026-05-24 13:04:22 +08:00
parent 7aa60e78f8 3d83740f88
commit 696920df73
292 changed files with 30774 additions and 218828 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/standards/playbook/scripts/playbook.py
+484 -190
View File
@@ -1,9 +1,12 @@
#!/usr/bin/env python3
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
from shutil import copy2, copytree, rmtree, which
import subprocess
import importlib.util
from typing import Optional
try:
import tomllib
@@ -21,10 +24,40 @@ ORDER = [
]
SCRIPT_DIR = Path(__file__).resolve().parent
PLAYBOOK_ROOT = SCRIPT_DIR.parent
MAIN_LOOP_SCRIPT = SCRIPT_DIR / "main_loop.py"
MAIN_LOOP_SPEC = importlib.util.spec_from_file_location("playbook_main_loop", MAIN_LOOP_SCRIPT)
assert MAIN_LOOP_SPEC and MAIN_LOOP_SPEC.loader
MAIN_LOOP = importlib.util.module_from_spec(MAIN_LOOP_SPEC)
MAIN_LOOP_SPEC.loader.exec_module(MAIN_LOOP)
PATH_CONFIG_KEYS = {"project_root", "deploy_root", "agents_home", "codex_home", "skill_link"}
DOCS_INDEX_SECTION_HEADINGS = {
"common": "## 跨语言（common）",
"tsl": "## TSL（tsl/tsf）",
"cpp": "## C++（cpp）",
"python": "## Python（python）",
"typescript": "## TypeScript（typescript）",
"markdown": "## Markdown（markdown）",
}
def usage() -> str:
return "Usage:\n python scripts/playbook.py -config <path>\n python scripts/playbook.py -h"
return (
"Usage:\n"
" python scripts/playbook.py -config <path>\n"
" python scripts/playbook.py -record-spec <spec_path> -progress <path>\n"
" python scripts/playbook.py -record-plan <plan_path> -progress <path>\n"
" python scripts/playbook.py -h"
)
def parse_cli_value(argv: list[str], flag: str) -> Optional[str]:
if flag not in argv:
return None
idx = argv.index(flag)
if idx + 1 >= len(argv):
return None
value = argv[idx + 1].strip()
return value or None
def strip_inline_comment(value: str) -> str:
@@ -141,8 +174,63 @@ def loads_toml_minimal(raw: str) -> dict:
return data
def normalize_path_config_strings(raw: str) -> str:
normalized_lines: list[str] = []
for line in raw.splitlines():
stripped = line.strip()
if not stripped or stripped.startswith("#") or "=" not in line:
normalized_lines.append(line)
continue
key_part, value_part = line.split("=", 1)
key = key_part.strip()
if key not in PATH_CONFIG_KEYS:
normalized_lines.append(line)
continue
value = strip_inline_comment(value_part.strip())
if len(value) < 2 or value[0] != '"' or value[-1] != '"' or "\\" not in value[1:-1]:
normalized_lines.append(line)
continue
inner = value[1:-1]
has_lone_backslash = False
probe_idx = 0
while probe_idx < len(inner):
if inner[probe_idx] != "\\":
probe_idx += 1
continue
if probe_idx + 1 < len(inner) and inner[probe_idx + 1] == "\\":
probe_idx += 2
continue
has_lone_backslash = True
break
if not has_lone_backslash:
normalized_lines.append(line)
continue
escaped: list[str] = []
idx = 0
while idx < len(inner):
ch = inner[idx]
if ch != "\\":
escaped.append(ch)
idx += 1
continue
if idx + 1 < len(inner) and inner[idx + 1] == "\\":
escaped.extend(["\\", "\\"])
idx += 2
continue
escaped.extend(["\\", "\\"])
idx += 1
normalized_lines.append(f'{key_part}= "{"".join(escaped)}"')
suffix = "\n" if raw.endswith("\n") else ""
return "\n".join(normalized_lines) + suffix
def load_config(path: Path) -> dict:
raw = path.read_text(encoding="utf-8")
raw = normalize_path_config_strings(path.read_text(encoding="utf-8"))
if tomllib is not None:
return tomllib.loads(raw)
return loads_toml_minimal(raw)
@@ -176,43 +264,87 @@ def normalize_langs(raw: object) -> list[str]:
return cleaned
def resolve_main_language(config: dict, context: dict) -> str:
raw = config.get("main_language")
if raw is not None and str(raw).strip():
return str(raw).strip()
full_config = context.get("config", {})
if isinstance(full_config, dict):
sync_conf = full_config.get("sync_standards")
if isinstance(sync_conf, dict):
langs_raw = sync_conf.get("langs")
if langs_raw is not None:
try:
langs = normalize_langs(langs_raw)
except ValueError:
langs = []
if langs:
return langs[0]
return "tsl"
def normalize_relative_dir(raw: object, label: str) -> str:
value = str(raw).strip()
if not value:
raise ValueError(f"{label} is empty")
path = Path(value)
if path.is_absolute() or ".." in path.parts:
raise ValueError(f"invalid {label}: {value}")
normalized = path.as_posix()
return "." if normalized == "" else normalized
def resolve_playbook_scripts(project_root: Path, context: dict) -> str:
playbook_scripts = PLAYBOOK_ROOT / "scripts"
def join_deploy_subpath(root: str, child: str) -> str:
if root in ("", "."):
return child.lstrip("/")
return f"{root.rstrip('/')}/{child.lstrip('/')}"
def resolve_in_project_deploy_root(project_root: Path) -> str | None:
try:
rel = playbook_scripts.resolve().relative_to(project_root.resolve())
return rel.as_posix()
rel = PLAYBOOK_ROOT.resolve().relative_to(project_root.resolve())
if str(rel) != ".":
return rel.as_posix()
except ValueError:
full_config = context.get("config", {})
if isinstance(full_config, dict):
vendor_conf = full_config.get("vendor")
if isinstance(vendor_conf, dict):
target_dir = vendor_conf.get("target_dir")
if target_dir:
target_str = str(target_dir).strip().rstrip("/").rstrip("\\")
if target_str:
return f"{target_str}/scripts"
return "docs/standards/playbook/scripts"
pass
return None
def config_requires_deploy_root(config: dict) -> bool:
for key in (
"vendor",
"sync_rules",
"sync_memory_bank",
"sync_prompts",
"sync_standards",
"install_skills",
):
if key in config:
return True
return False
def resolve_configured_deploy_root(config: dict, project_root: Path) -> str:
playbook_config = config.get("playbook", {})
raw = None
if isinstance(playbook_config, dict):
raw = playbook_config.get("deploy_root")
vendor_config = config.get("vendor", {})
if isinstance(vendor_config, dict) and vendor_config.get("target_dir") is not None:
raise ValueError(
"vendor.target_dir is no longer supported; use [playbook].deploy_root"
)
if raw is not None and str(raw).strip():
return normalize_relative_dir(raw, "deploy_root")
in_project_deploy_root = resolve_in_project_deploy_root(project_root)
if in_project_deploy_root is not None:
return in_project_deploy_root
if config_requires_deploy_root(config):
raise ValueError(
"playbook.deploy_root is required when running from an external clone; "
"set it to the target project's relative deployment path"
)
return "docs/standards/playbook"
def resolve_deploy_root(context: dict) -> str:
project_root: Path = context["project_root"]
in_project_deploy_root = resolve_in_project_deploy_root(project_root)
if in_project_deploy_root is not None:
return in_project_deploy_root
return context["deploy_root"]
def resolve_docs_prefix(context: dict) -> str:
return join_deploy_subpath(resolve_deploy_root(context), "docs")
def resolve_playbook_scripts(context: dict) -> str:
return join_deploy_subpath(resolve_deploy_root(context), "scripts")
def read_git_commit(root: Path) -> str:
@@ -228,88 +360,75 @@ def read_git_commit(root: Path) -> str:
return result.stdout.strip() or "N/A"
def write_docs_index(dest_prefix: Path, langs: list[str]) -> None:
lines = [
"# 文档导航（Docs Index）",
def extract_docs_index_sections(lines: list[str]) -> dict[str, list[str]]:
heading_to_key = {value: key for key, value in DOCS_INDEX_SECTION_HEADINGS.items()}
starts: list[tuple[int, str]] = []
for idx, line in enumerate(lines):
key = heading_to_key.get(line)
if key is not None:
starts.append((idx, key))
sections: dict[str, list[str]] = {}
for idx, (start, key) in enumerate(starts):
end = starts[idx + 1][0] if idx + 1 < len(starts) else len(lines)
section_lines = lines[start:end]
while section_lines and section_lines[-1] == "":
section_lines = section_lines[:-1]
sections[key] = section_lines
return sections
def build_docs_index_lines(langs: list[str], source_path: Path | None = None) -> list[str]:
docs_index_path = source_path or (PLAYBOOK_ROOT / "docs" / "index.md")
source_lines = docs_index_path.read_text(encoding="utf-8").splitlines()
title = source_lines[0] if source_lines else "# 文档导航（Docs Index）"
sections = extract_docs_index_sections(source_lines)
ordered_keys = ["common", *langs]
result = [
title,
"",
f"本快照为裁剪版 Playbook（langs: {','.join(langs)}）。",
"",
"## 跨语言（common）",
"",
"- 提交信息与版本号：`common/commit_message.md`",
]
for lang in langs:
if lang == "tsl":
lines += [
"",
"## TSL（tsl）",
"",
"- 代码风格：`tsl/code_style.md`",
"- 命名规范：`tsl/naming.md`",
"- 语法手册：`tsl/syntax_book/index.md`",
"- 工具链与验证命令（模板）：`tsl/toolchain.md`",
]
elif lang == "cpp":
lines += [
"",
"## C++（cpp）",
"",
"- 代码风格：`cpp/code_style.md`",
"- 命名规范：`cpp/naming.md`",
"- 工具链与验证命令（模板）：`cpp/toolchain.md`",
"- 第三方依赖（Conan）：`cpp/dependencies_conan.md`",
"- clangd 配置：`cpp/clangd.md`",
]
elif lang == "python":
lines += [
"",
"## Python（python）",
"",
"- 代码风格：`python/style_guide.md`",
"- 工具链：`python/tooling.md`",
"- 配置清单：`python/configuration.md`",
]
elif lang == "typescript":
lines += [
"",
"## TypeScript（typescript）",
"",
"- 代码风格：`typescript/code_style.md`",
"- 命名规范：`typescript/naming.md`",
"- 工具链：`typescript/toolchain.md`",
"- 配置清单：`typescript/configuration.md`",
]
elif lang == "markdown":
lines += [
"",
"## Markdown（markdown）",
"",
"- 代码块与行内代码格式：`markdown/index.md`",
]
for idx, key in enumerate(ordered_keys):
section = sections.get(key)
if section is None:
raise ValueError(f"docs/index.md is missing section for {key}")
if idx > 0:
result.append("")
result.extend(section)
return result
def write_docs_index(dest_prefix: Path, langs: list[str]) -> None:
lines = build_docs_index_lines(langs)
docs_index = dest_prefix / "docs/index.md"
ensure_dir(docs_index.parent)
docs_index.write_text("\n".join(lines) + "\n", encoding="utf-8")
def write_snapshot_readme(dest_prefix: Path, langs: list[str]) -> None:
def write_snapshot_readme(dest_prefix: Path, deploy_root: str, langs: list[str]) -> None:
scripts_path = join_deploy_subpath(deploy_root, "scripts/playbook.py")
docs_index_path = join_deploy_subpath(deploy_root, "docs/index.md")
lines = [
"# Playbook（裁剪快照）",
"",
f"本目录为从 Playbook vendoring 的裁剪快照（langs: {','.join(langs)}）。",
f"本目录为从 Playbook 部署到项目内的裁剪快照（langs: {','.join(langs)}）。",
"",
"## 使用",
"",
"在目标项目根目录执行：",
"",
"```sh",
"python docs/standards/playbook/scripts/playbook.py -config playbook.toml",
f"python {scripts_path} -config playbook.toml",
"```",
"",
"配置示例：`docs/standards/playbook/playbook.toml.example`",
f"配置示例：`{join_deploy_subpath(deploy_root, 'playbook.toml.example')}`",
"",
"文档入口：",
"",
"- `docs/standards/playbook/docs/index.md`",
f"- `{docs_index_path}`",
"- `.agents/index.md`",
]
(dest_prefix / "README.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
@@ -337,11 +456,8 @@ def vendor_action(config: dict, context: dict) -> int:
print(f"ERROR: {exc}", file=sys.stderr)
return 2
target_dir = config.get("target_dir", "docs/standards/playbook")
target_path = Path(target_dir)
if target_path.is_absolute() or ".." in target_path.parts:
print(f"ERROR: invalid target_dir: {target_dir}", file=sys.stderr)
return 2
deploy_root = context["deploy_root"]
target_path = Path(deploy_root)
project_root: Path = context["project_root"]
dest_prefix = project_root / target_path
@@ -362,7 +478,7 @@ def vendor_action(config: dict, context: dict) -> int:
copy2(gitattributes_src, dest_prefix / ".gitattributes")
copytree(PLAYBOOK_ROOT / "scripts", dest_prefix / "scripts")
copytree(PLAYBOOK_ROOT / "codex", dest_prefix / "codex")
copytree(PLAYBOOK_ROOT / "skills", dest_prefix / "skills")
copy2(PLAYBOOK_ROOT / "SKILLS.md", dest_prefix / "SKILLS.md")
common_docs = PLAYBOOK_ROOT / "docs/common"
@@ -415,7 +531,7 @@ def vendor_action(config: dict, context: dict) -> int:
copy2(example_config, dest_prefix / "playbook.toml.example")
write_docs_index(dest_prefix, langs)
write_snapshot_readme(dest_prefix, langs)
write_snapshot_readme(dest_prefix, deploy_root, langs)
write_source_file(dest_prefix, langs)
log(f"Vendored snapshot -> {dest_prefix}")
@@ -426,14 +542,11 @@ def replace_placeholders(
text: str,
project_name: str | None,
date_value: str,
main_language: str | None,
playbook_scripts: str | None,
) -> str:
result = text.replace("{{DATE}}", date_value)
if project_name:
result = result.replace("{{PROJECT_NAME}}", project_name)
if main_language:
result = result.replace("{{MAIN_LANGUAGE}}", main_language)
if playbook_scripts:
result = result.replace("{{PLAYBOOK_SCRIPTS}}", playbook_scripts)
return result
@@ -448,41 +561,16 @@ def backup_path(path: Path, no_backup: bool) -> None:
log(f"Backed up: {path} -> {backup}")
def rename_template_files(root: Path) -> None:
for template in root.rglob("*.template.md"):
target = template.with_name(template.name.replace(".template.md", ".md"))
template.rename(target)
def replace_placeholders_in_dir(
root: Path,
project_name: str | None,
date_value: str,
main_language: str | None,
playbook_scripts: str | None,
) -> None:
for file_path in root.rglob("*.md"):
text = file_path.read_text(encoding="utf-8")
updated = replace_placeholders(
text, project_name, date_value, main_language, playbook_scripts
)
if updated != text:
file_path.write_text(updated, encoding="utf-8")
def replace_placeholders_in_file(
file_path: Path,
project_name: str | None,
date_value: str,
main_language: str | None,
playbook_scripts: str | None,
) -> None:
if file_path.suffix != ".md":
return
text = file_path.read_text(encoding="utf-8")
updated = replace_placeholders(
text, project_name, date_value, main_language, playbook_scripts
)
updated = replace_placeholders(text, project_name, date_value, playbook_scripts)
if updated != text:
file_path.write_text(updated, encoding="utf-8")
@@ -501,7 +589,6 @@ def sync_directory(
target_dir: Path,
project_name: str | None,
date_value: str,
main_language: str | None,
playbook_scripts: str | None,
force: bool,
no_backup: bool,
@@ -522,7 +609,6 @@ def sync_directory(
target_file,
project_name,
date_value,
main_language,
playbook_scripts,
)
@@ -550,12 +636,11 @@ def update_agents_section(
end_marker: str,
project_name: str | None,
date_value: str,
main_language: str | None,
playbook_scripts: str | None,
) -> None:
template_text = template_path.read_text(encoding="utf-8")
template_text = replace_placeholders(
template_text, project_name, date_value, main_language, playbook_scripts
template_text, project_name, date_value, playbook_scripts
)
block = extract_block_lines(template_text, start_marker, end_marker)
if not block:
@@ -631,8 +716,7 @@ def sync_agents_template(context: dict) -> int:
return 0
project_name = resolve_project_name(context)
main_language = resolve_main_language({}, context)
playbook_scripts = resolve_playbook_scripts(project_root, context)
playbook_scripts = resolve_playbook_scripts(context)
date_value = resolve_template_date(context)
agents_dst = project_root / "AGENTS.md"
@@ -658,12 +742,85 @@ def sync_agents_template(context: dict) -> int:
end_marker,
project_name,
date_value,
main_language,
playbook_scripts,
)
sync_claude_md(project_root, context.get("config", {}))
return 0
_CLAUDE_BLOCK_START = "<!-- playbook:claude:start -->"
_CLAUDE_BLOCK_END = "<!-- playbook:claude:end -->"
_CLAUDE_MD_CANDIDATES = ["CLAUDE.md", ".claude/CLAUDE.md"]
def sync_claude_md(project_root: Path, config: dict) -> None:
claude_md_config = config.get("playbook", {}).get("claude_md")
claude_md: Path | None = None
if claude_md_config:
claude_md = project_root / claude_md_config
else:
for candidate in _CLAUDE_MD_CANDIDATES:
path = project_root / candidate
if path.exists():
claude_md = path
break
if claude_md is None:
claude_md = project_root / "CLAUDE.md"
rel_prefix = ""
try:
rel = claude_md.parent.resolve().relative_to(project_root.resolve())
if rel != Path("."):
depth = len(rel.parts)
rel_prefix = "../" * depth
except ValueError:
pass
block_lines = [
_CLAUDE_BLOCK_START,
"",
f"@{rel_prefix}AGENTS.md",
f"@{rel_prefix}AGENT_RULES.md",
"",
_CLAUDE_BLOCK_END,
]
if not claude_md.exists():
ensure_dir(claude_md.parent)
claude_md.write_text("\n".join(block_lines) + "\n", encoding="utf-8")
log(f"Created {claude_md.relative_to(project_root)} with playbook block.")
return
text = claude_md.read_text(encoding="utf-8")
if _CLAUDE_BLOCK_START in text:
lines = text.splitlines()
updated: list[str] = []
in_block = False
replaced = False
for line in lines:
if not replaced and line.strip() == _CLAUDE_BLOCK_START:
updated.extend(block_lines)
in_block = True
replaced = True
continue
if in_block:
if line.strip() == _CLAUDE_BLOCK_END:
in_block = False
continue
updated.append(line)
claude_md.write_text("\n".join(updated) + "\n", encoding="utf-8")
log("Updated CLAUDE.md (playbook block).")
elif "@AGENTS.md" in text:
log("Skip: CLAUDE.md already references AGENTS.md")
else:
appended = text.rstrip("\n") + "\n\n" + "\n".join(block_lines) + "\n"
claude_md.write_text(appended, encoding="utf-8")
log("Appended playbook block to CLAUDE.md")
def should_sync_agents(config: dict) -> bool:
for key in ("sync_rules", "sync_memory_bank", "sync_prompts", "sync_standards"):
if key in config:
@@ -690,18 +847,32 @@ def sync_rules_action(config: dict, context: dict) -> int:
return 0
project_name = resolve_project_name(context)
main_language = resolve_main_language(config, context)
playbook_scripts = resolve_playbook_scripts(project_root, context)
playbook_scripts = resolve_playbook_scripts(context)
date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
no_backup = bool(config.get("no_backup", False))
backup_path(rules_dst, no_backup)
text = rules_src.read_text(encoding="utf-8")
text = replace_placeholders(
text, project_name, date_value, main_language, playbook_scripts
)
rules_dst.write_text(text + "\n", encoding="utf-8")
text = replace_placeholders(text, project_name, date_value, playbook_scripts)
rules_dst.write_text(text.rstrip("\n") + "\n", encoding="utf-8")
log("Synced: AGENT_RULES.md")
local_rules = project_root / "AGENT_RULES.local.md"
if not local_rules.exists():
local_rules.write_text(
"# AGENT_RULES.local\n"
"\n"
"项目私有规则（优先级高于 AGENT_RULES.md）。\n"
"\n"
"在此记录：\n"
"\n"
"- 项目特有的注意事项与常见陷阱\n"
"- 同一错误发生 2 次以上时的修正规则\n"
"- 团队约定的额外约束\n",
encoding="utf-8",
)
log("Created: AGENT_RULES.local.md")
return 0
@@ -718,8 +889,7 @@ def sync_memory_bank_action(config: dict, context: dict) -> int:
return 2
project_name = config.get("project_name")
main_language = resolve_main_language(config, context)
playbook_scripts = resolve_playbook_scripts(project_root, context)
playbook_scripts = resolve_playbook_scripts(context)
date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
force = bool(config.get("force", False))
no_backup = bool(config.get("no_backup", False))
@@ -731,7 +901,6 @@ def sync_memory_bank_action(config: dict, context: dict) -> int:
memory_dst,
project_name,
date_value,
main_language,
playbook_scripts,
force,
no_backup,
@@ -753,8 +922,7 @@ def sync_prompts_action(config: dict, context: dict) -> int:
return 2
project_name = resolve_project_name(context)
main_language = resolve_main_language(config, context)
playbook_scripts = resolve_playbook_scripts(project_root, context)
playbook_scripts = resolve_playbook_scripts(context)
date_value = config.get("date") or datetime.now().strftime("%Y-%m-%d")
force = bool(config.get("force", False))
no_backup = bool(config.get("no_backup", False))
@@ -767,7 +935,6 @@ def sync_prompts_action(config: dict, context: dict) -> int:
prompts_dst,
project_name,
date_value,
main_language,
playbook_scripts,
force,
no_backup,
@@ -830,8 +997,13 @@ def update_agents_block(agents_md: Path, block_lines: list[str]) -> None:
def create_agents_index(agents_root: Path, langs: list[str], docs_prefix: str | None) -> None:
agents_index = agents_root / "index.md"
if agents_index.exists():
return
lang_descriptions = {
"tsl": "TSL 相关规则集（由 playbook 同步；适用于 `.tsl`/`.tsf`）",
"cpp": "C++ 相关规则集（由 playbook 同步；适用于 C++23/Modules）",
"python": "Python 相关规则集（由 playbook 同步）",
"typescript": "TypeScript/JavaScript 相关规则集（由 playbook 同步）",
"markdown": "Markdown 相关规则集（仅代码格式化）",
}
lines = [
"# .agents（多语言）",
"",
@@ -839,11 +1011,11 @@ def create_agents_index(agents_root: Path, langs: list[str], docs_prefix: str |
"",
"建议约定：",
"",
"- `.agents/tsl/`：TSL 相关规则集（由 playbook 同步；适用于 `.tsl`/`.tsf`）",
"- `.agents/cpp/`：C++ 相关规则集（由 playbook 同步；适用于 C++23/Modules）",
"- `.agents/python/`：Python 相关规则集（由 playbook 同步）",
"- `.agents/typescript/`：TypeScript/JavaScript 相关规则集（由 playbook 同步）",
"- `.agents/markdown/`：Markdown 相关规则集（仅代码格式化）",
]
for lang in langs:
description = lang_descriptions.get(lang, "相关规则集（由 playbook 同步）")
lines.append(f"- `.agents/{lang}/`：{description}")
lines += [
"",
"规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。",
"",
@@ -856,32 +1028,45 @@ def create_agents_index(agents_root: Path, langs: list[str], docs_prefix: str |
"",
"标准快照文档入口：",
"",
f"- {docs_prefix or 'docs/standards/playbook/docs/'}",
f"- {docs_prefix or 'docs/'}",
]
agents_index.write_text("\n".join(lines) + "\n", encoding="utf-8")
log("Created .agents/index.md")
log("Synced .agents/index.md")
def rewrite_agents_docs_links(agents_dir: Path, docs_prefix: str) -> None:
def rewrite_docs_links_in_markdown(root: Path, docs_prefix: str, recursive: bool) -> None:
replacements = {
"`docs/tsl/": f"`{docs_prefix}/tsl/",
"`docs/cpp/": f"`{docs_prefix}/cpp/",
"`docs/python/": f"`{docs_prefix}/python/",
"`docs/typescript/": f"`{docs_prefix}/typescript/",
"`docs/markdown/": f"`{docs_prefix}/markdown/",
"`docs/common/": f"`{docs_prefix}/common/",
"tsl": f"{docs_prefix}/tsl/",
"cpp": f"{docs_prefix}/cpp/",
"python": f"{docs_prefix}/python/",
"typescript": f"{docs_prefix}/typescript/",
"markdown": f"{docs_prefix}/markdown/",
"common": f"{docs_prefix}/common/",
}
for md_path in agents_dir.glob("*.md"):
iterator = root.rglob("*.md") if recursive else root.glob("*.md")
patterns = [
(re.compile(rf"(?<![\w./-])docs/{section}/"), replacement)
for section, replacement in replacements.items()
]
for md_path in iterator:
if not md_path.is_file():
continue
text = md_path.read_text(encoding="utf-8")
updated = text
for old, new in replacements.items():
updated = updated.replace(old, new)
for pattern, replacement in patterns:
updated = pattern.sub(replacement, updated)
if updated != text:
md_path.write_text(updated, encoding="utf-8")
def rewrite_agents_docs_links(agents_dir: Path, docs_prefix: str) -> None:
rewrite_docs_links_in_markdown(agents_dir, docs_prefix, recursive=False)
def rewrite_skill_docs_links(skill_dir: Path, docs_prefix: str) -> None:
rewrite_docs_links_in_markdown(skill_dir, docs_prefix, recursive=True)
def read_gitattributes_entries(path: Path) -> list[str]:
entries: list[str] = []
for line in path.read_text(encoding="utf-8").splitlines():
@@ -993,13 +1178,7 @@ def sync_standards_action(config: dict, context: dict) -> int:
copytree(src, dst)
log(f"Synced .agents/{lang} from standards.")
docs_prefix = None
try:
rel_snapshot = PLAYBOOK_ROOT.resolve().relative_to(project_root.resolve())
if str(rel_snapshot) != ".":
docs_prefix = f"{rel_snapshot.as_posix()}/docs"
except ValueError:
docs_prefix = None
docs_prefix = resolve_docs_prefix(context)
if docs_prefix:
for lang in langs:
@@ -1075,7 +1254,8 @@ def install_skills_action(config: dict, context: dict) -> int:
if not agents_home.is_absolute():
agents_home = (context["project_root"] / agents_home).resolve()
skills_src_root = PLAYBOOK_ROOT / "codex/skills"
skills_src_root = PLAYBOOK_ROOT / "skills"
skills_thirdparty_root = skills_src_root / "thirdparty"
if not skills_src_root.is_dir():
print(f"ERROR: skills source not found: {skills_src_root}", file=sys.stderr)
return 2
@@ -1084,38 +1264,104 @@ def install_skills_action(config: dict, context: dict) -> int:
ensure_dir(skills_dst_root)
if mode == "all":
skills = [
path.name
own_skills = [
(path.name, skills_src_root, "own")
for path in skills_src_root.iterdir()
if path.is_dir() and not path.name.startswith(".")
if path.is_dir() and not path.name.startswith(".") and path.name != "thirdparty"
]
third_skills = [
(path.name, skills_thirdparty_root, "thirdparty")
for path in skills_thirdparty_root.iterdir()
if path.is_dir() and not path.name.startswith(".")
] if skills_thirdparty_root.is_dir() else []
skill_entries = own_skills + third_skills
elif mode == "list":
try:
skills = normalize_names(config.get("skills"), "skills")
names = normalize_names(config.get("skills"), "skills")
except ValueError as exc:
print(f"ERROR: {exc}", file=sys.stderr)
return 2
skill_entries = []
for name in names:
if (skills_src_root / name).is_dir():
skill_entries.append((name, skills_src_root, "own"))
elif skills_thirdparty_root.is_dir() and (skills_thirdparty_root / name).is_dir():
skill_entries.append((name, skills_thirdparty_root, "thirdparty"))
else:
print(f"ERROR: skill not found: {name}", file=sys.stderr)
return 2
else:
print("ERROR: mode must be list or all", file=sys.stderr)
return 2
timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
for name in skills:
src = skills_src_root / name
if not src.is_dir():
print(f"ERROR: skill not found: {name}", file=sys.stderr)
return 2
no_backup = bool(config.get("no_backup", False))
for name, src_root, origin in skill_entries:
src = src_root / name
dst = skills_dst_root / name
if dst.exists():
backup = skills_dst_root / f"{name}.bak.{timestamp}"
dst.rename(backup)
log(f"Backed up existing skill: {name} -> {backup.name}")
if no_backup:
rmtree(dst)
else:
backup = skills_dst_root / f"{name}.bak.{timestamp}"
dst.rename(backup)
log(f"Backed up existing skill: {name} -> {backup.name}")
copytree(src, dst)
log(f"Installed: {name}")
rewrite_skill_docs_links(dst, resolve_docs_prefix(context))
tag = " [thirdparty]" if origin == "thirdparty" else ""
log(f"Installed: {name}{tag}")
skill_link_raw = config.get("skill_link")
if skill_link_raw:
skill_link_home = Path(str(skill_link_raw)).expanduser()
if not skill_link_home.is_absolute():
skill_link_home = (context["project_root"] / skill_link_home).resolve()
_create_skills_symlink(skill_link_home / "skills", skills_dst_root)
return 0
def _is_junction(path: Path) -> bool:
if sys.platform != "win32":
return False
try:
import ctypes.wintypes
attrs = ctypes.windll.kernel32.GetFileAttributesW(str(path))
return attrs != -1 and bool(attrs & 0x400)
except Exception:
return False
def _create_skills_symlink(link_path: Path, target_path: Path) -> None:
if link_path.is_symlink() or _is_junction(link_path):
if link_path.resolve() == target_path.resolve():
log(f"Symlink already up to date: {link_path}")
return
if link_path.is_symlink():
link_path.unlink()
elif _is_junction(link_path):
link_path.rmdir()
elif link_path.exists():
log(f"Skip symlink: {link_path} exists and is not a symlink")
return
ensure_dir(link_path.parent)
try:
link_path.symlink_to(target_path, target_is_directory=True)
log(f"Created symlink: {link_path} -> {target_path}")
except OSError:
if sys.platform == "win32":
result = subprocess.run(
["cmd", "/c", "mklink", "/J", str(link_path), str(target_path)],
capture_output=True,
)
if result.returncode == 0:
log(f"Created junction: {link_path} -> {target_path}")
else:
log(f"Warning: could not create junction {link_path}")
else:
log(f"Warning: could not create symlink {link_path}")
def format_md_action(config: dict, context: dict) -> int:
tool = str(config.get("tool", "prettier")).lower()
if tool != "prettier":
@@ -1170,6 +1416,47 @@ def main(argv: list[str]) -> int:
if "-h" in argv or "-help" in argv:
print(usage())
return 0
spec_path = parse_cli_value(argv, "-record-spec")
if spec_path is not None:
progress_path = parse_cli_value(argv, "-progress")
if not progress_path:
print("ERROR: -progress is required.\n" + usage(), file=sys.stderr)
return 2
code, message = MAIN_LOOP.record_workflow_state(
Path(progress_path),
"planning",
spec_path,
None,
None,
None,
)
if code != 0:
print(message, file=sys.stderr)
return code
print(message)
return 0
plan_path = parse_cli_value(argv, "-record-plan")
if plan_path is not None:
progress_path = parse_cli_value(argv, "-progress")
if not progress_path:
print("ERROR: -progress is required.\n" + usage(), file=sys.stderr)
return 2
code, message = MAIN_LOOP.record_workflow_state(
Path(progress_path),
"planning",
None,
plan_path,
"executing-plans",
"karpathy-guidelines,.agents,AGENT_RULES",
)
if code != 0:
print(message, file=sys.stderr)
return code
print(message)
return 0
if "-config" not in argv:
print("ERROR: -config is required.\n" + usage(), file=sys.stderr)
return 2
@@ -1192,10 +1479,17 @@ def main(argv: list[str]) -> int:
root = (config_path.parent / root).resolve()
else:
root = config_path.parent
resolved_root = root.resolve()
try:
deploy_root = resolve_configured_deploy_root(config, resolved_root)
except ValueError as exc:
print(f"ERROR: {exc}", file=sys.stderr)
return 2
context = {
"project_root": root.resolve(),
"project_root": resolved_root,
"config_path": config_path.resolve(),
"config": config,
"deploy_root": deploy_root,
}
if should_sync_agents(config):