feat(skill): 'sca skill targets|install' + skill source shipped in wheel

The wheel force-includes the uncompiled docs/skill source tree and
skillproj.toml as package resources; compilation happens at install
time on the user's machine, so no repository checkout is needed.

The compiler moves to simplecadapi.skill.compiler; tools/skillbuild.py
stays as the maintainer-side wrapper over the same code.

'sca skill install' compiles into <skills-dir>/simplecadapi (location
resolved through the existing addon config/env chain, default
~/.agents/skills; no sca init required) and refuses to overwrite
without --force, which only permits replacing a directory whose
SKILL.md declares the same skill name.
This commit is contained in:
NiJingzhe
2026-09-18 10:54:13 +08:00
parent ebe391af01
commit 264a904f8b
10 changed files with 833 additions and 471 deletions
+32 -5
View File
@@ -214,6 +214,29 @@ For local development from this repository:
uv sync --group dev
```
### Agent Skill
After installing with pip above, install the bundled skill for your agent
harness:
```bash
sca skill targets
# Default location (~/.agents/skills), or select ZCode's explicitly:
sca skill install --target zcode --skills-dir ~/.zcode/skills
```
`targets` lists the available harness targets. `install` compiles the bundled
source and writes it to `<skills-dir>/simplecadapi`; without `--skills-dir`,
it uses the existing addon configuration/environment resolution, falling back
to `~/.agents/skills`; `sca init` is not required. The wheel includes the
uncompiled `docs/skill/` source tree and `skillproj.toml` as package
resources — compilation happens on install, no repository checkout needed.
With `uv`, prefix these commands with `uv run`.
`install` fails if the destination already exists. Add `--force` to replace it
only if it is a directory whose `SKILL.md` declares the matching skill name
(`simplecadapi`); unrelated directories cannot be overwritten.
## Quick Start
```python
@@ -557,11 +580,14 @@ against a target STEP (see `examples/bowl_connector/`).
## Releasing the Agent Skill
The skill source tree lives under `docs/skill/` and stays harness-neutral.
`tools/skillbuild.py` compiles it per harness target (targets and output
directories are configured in `skillproj.toml`; the outputs under
`skills/simplecadapi-*/` are regenerable build artifacts and are not
`tools/skillbuild.py` wraps the same compiler the `sca skill` CLI uses, for
maintainer builds in this repository: it compiles per harness target (targets
and default output directories are configured in `skillproj.toml`; the outputs
under `skills/simplecadapi-*/` are regenerable build artifacts and are not
committed). Harness-specific text, when it is ever needed, is marked with
`<!-- skill:if ... -->` conditional blocks that compile per target.
`<!-- skill:if ... -->` conditional blocks that compile per target. The wheel
itself never contains precompiled targets — end users install from the
bundled source with `sca skill install`.
From a clean checkout, update the project version and documentation, then
build and validate the release artifacts:
@@ -584,7 +610,8 @@ tar -tzf skills/simplecadapi.tar.gz | head
```
Commit only the `docs/skill/` source tree; the release workflow builds the
harness outputs and uploads the archive to the GitHub release.
harness outputs and uploads the archive to the GitHub release. Prefer
`sca skill` for installation from a pip-installed package.
## Development
+35 -7
View File
@@ -184,6 +184,25 @@ uv add simplecadapi
uv sync --group dev
```
### Agent Skill
pip 安装完成后,为你的 agent harness 安装内置 skill:
```bash
sca skill targets
# 默认位置(~/.agents/skills),或显式指定 ZCode 的 skills 目录:
sca skill install --target zcode --skills-dir ~/.zcode/skills
```
`targets` 列出可用的 harness 目标。`install` 编译内置源码并写入
`<skills-dir>/simplecadapi`;不传 `--skills-dir` 时,沿用既有 addon 配置/
环境解析,默认回退到 `~/.agents/skills`,不要求先执行 `sca init`。wheel
内置的是未编译的 `docs/skill/` 源树和 `skillproj.toml` 资源,编译发生在
安装时机;无需 checkout 本仓库。使用 `uv` 时,上述命令前缀 `uv run`。
`install` 在目标位置已存在时报错。加 `--force` 允许替换,但仅限
`SKILL.md` 声明了同名 skill(`simplecadapi`)的目录;无关目录不会被覆盖。
## 快速开始
```python
@@ -386,24 +405,33 @@ uv run --extra fem python examples/ap242_gmsh_volume_mesh/study_mesh_convergence
## 发布 Agent Skill
仓库中的 `skills/simplecadapi/` 是精简版 Agent Skill。它包含生成的 API 和建模参考文档,但不包含 SDK 源代码。
skill 源树位于 `docs/skill/`,保持 harness 中立。`tools/skillbuild.py` 是
`sca skill` CLI 所用同一编译器的封装,供本仓库维护者构建:按 harness 目标
编译(目标与默认输出目录配置在 `skillproj.toml`;`skills/simplecadapi-*/`
下的输出是可再生的构建产物,不提交入库)。如需 harness 特定文本,用
`<!-- skill:if ... -->` 条件块标记,按目标编译。wheel 本身不包含任何预编译
目标——终端用户用 `sca skill install` 从内置源码自行安装。
在干净的工作区中更新项目版本和文档,然后生成并验证发布产物:
```bash
uv sync --group dev
uv run skill-pack --refresh-docs --archive
uv run python -m pytest test/test_skill_pack.py
uv run python tools/auto_docs_gen.py --quiet
uv run python tools/skillbuild.py --target omp
uv run pytest test/test_skill_build.py
tar -C skills -czf skills/simplecadapi.tar.gz simplecadapi-omp
```
该命令会刷新生成文档、重建 `skills/simplecadapi/`,并生成 `skills/simplecadapi.tar.gz`。发布前检查 Skill 内容和归档文件:
这组命令会重新生成 skill 源树内的 API 参考、重新编译 omp 目标,并生成
`skills/simplecadapi.tar.gz`。发布前检查源树和编译产物:
```bash
git diff -- skills/simplecadapi docs
tar -tzf skills/simplecadapi.tar.gz
git diff -- docs/skill
tar -tzf skills/simplecadapi.tar.gz | head
```
发布时提交生成的 `skills/simplecadapi/` 目录和更新后的 `docs/`。归档文件已被 Git 忽略;请将 `skills/simplecadapi.tar.gz` 附加到对应的 GitHub Release,或上传到目标 Agent Skills 注册中心。
发布时只提交 `docs/skill/` 源树;harness 编译产物由发布工作流生成,归档
文件上传到 GitHub Release。通过 pip 安装后,优先使用 `sca skill` 构建和安装。
## 开发
+6 -3
View File
@@ -73,12 +73,14 @@ build-backend = "hatchling.build"
# Metadata-Version 2.5 is newer than what twine 6.x validates; keep the
# published metadata at 2.4 until the toolchain accepts 2.5.
core-metadata-version = "2.4"
# The Python package ships code only. Generated skill docs live in docs/skill
# (built by tools/auto_docs_gen.py + tools/skillbuild.py) and are distributed
# as the Agent Skill archive, not inside the wheel.
# Ship harness-neutral source; sca skill compiles it on the user's machine.
packages = ["src/simplecadapi"]
include = ["src/**/*"]
[tool.hatch.build.targets.wheel.force-include]
"docs/skill" = "simplecadapi/skill/resources/docs/skill"
"skillproj.toml" = "simplecadapi/skill/resources/skillproj.toml"
[tool.hatch.build.targets.sdist]
core-metadata-version = "2.4"
include = [
@@ -86,6 +88,7 @@ include = [
"/LICENSE",
"/pyproject.toml",
"/MANIFEST.in",
"/skillproj.toml",
"/src",
"/docs",
]
+5 -1
View File
@@ -5,6 +5,7 @@ Groups, each owned by its module and registered here at parser level so
sca init # machine setup: addon home + shell wiring
sca addon add|update|remove|list|use
sca skill targets|install
sca cache status|verify|prune|clear
sca export <package.scadpkg> [--format ...]
@@ -23,12 +24,14 @@ from typing import Any, Sequence
from .addon import AddonError
from .addon.install import sca_version
from .skill.compiler import SkillBuildError
def build_parser() -> argparse.ArgumentParser:
from .addon import cli as addon_cli
from .cache import cli as cache_cli
from .exporter import cli as exporter_cli
from .skill import cli as skill_cli
parser = argparse.ArgumentParser(
prog="sca",
@@ -42,6 +45,7 @@ def build_parser() -> argparse.ArgumentParser:
addon_cli.configure(subparsers)
cache_cli.configure(subparsers)
exporter_cli.configure(subparsers)
skill_cli.configure(subparsers)
return parser
@@ -55,7 +59,7 @@ def run(argv: Sequence[str] | None = None) -> tuple[dict[str, Any], int, Any]:
def main(argv: Sequence[str] | None = None) -> int:
try:
report, exit_code, printer = run(argv)
except (AddonError, OSError, ValueError) as exc:
except (AddonError, SkillBuildError, OSError, ValueError) as exc:
print(f"sca: {type(exc).__name__}: {exc}", file=sys.stderr)
return 2
printer(report)
+34
View File
@@ -0,0 +1,34 @@
"""Skill compilation and installation for SimpleCADAPI.
The wheel ships the uncompiled skill source tree (``docs/skill`` plus
``skillproj.toml``) as package resources; this module compiles it into
per-harness builds at install time via the ``sca skill`` command group.
``tools/skillbuild.py`` is a thin wrapper around the same compiler for
maintainer-side builds from a checkout.
"""
from __future__ import annotations
from .compiler import (
Condition,
SkillBuildError,
SkillProject,
SourceFile,
build_target,
collect_source_files,
compile_text,
find_project_root,
load_project,
)
__all__ = [
"Condition",
"SkillBuildError",
"SkillProject",
"SourceFile",
"build_target",
"collect_source_files",
"compile_text",
"find_project_root",
"load_project",
]
+57
View File
@@ -0,0 +1,57 @@
"""The ``sca skill`` command group."""
from __future__ import annotations
import argparse
from pathlib import Path
from typing import Any
from ..addon.home import resolve_paths
from .runtime import build_skill, bundled_project
def configure(subparsers: argparse._SubParsersAction) -> None:
skill = subparsers.add_parser(
"skill", help="install the bundled Agent Skill for a harness"
)
commands = skill.add_subparsers(dest="command", required=True)
commands.add_parser("targets", help="list supported harness targets")
install = commands.add_parser(
"install", help="compile the bundled skill into <skills-dir>/<skill name>"
)
install.add_argument(
"--target", required=True, help="harness target; see sca skill targets"
)
install.add_argument(
"--skills-dir", type=Path,
help="skills parent directory (default: config/env or ~/.agents/skills)",
)
install.add_argument(
"--force", action="store_true",
help="replace an existing install of this same skill",
)
skill.set_defaults(handler=_run, printer=_print)
def _run(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
project = bundled_project()
if args.command == "targets":
return {"targets": list(project.targets)}, 0
skills_dir = resolve_paths(skills_dir=args.skills_dir).skills_dir
report = build_skill(
project=project,
target=args.target,
output=skills_dir / project.name,
force=args.force,
)
report["action"] = "install"
return report, 0
def _print(report: dict[str, Any]) -> None:
if "targets" in report:
print("\n".join(report["targets"]))
else:
print(
f"installed {report['name']} for {report['target']}: "
f"{report['files']} files -> {report['output']}"
)
+460
View File
@@ -0,0 +1,460 @@
#!/usr/bin/env python3
"""Compile a skill tree into per-target harness builds.
The tree layout is the filesystem under the source root configured in
skillproj.toml. This tool adds nothing, moves nothing, and invents no
layout. Its single job is conditional compilation:
<!-- skill:if omp,!claude -->
harness-specific text
<!-- skill:endif -->
A block is included in the build for target T iff T appears as a
positive name and not as a negated name. An expression with only
negations includes every target not negated. There is no else and no
nesting: complementary blocks express else, and a nesting need means
the file should be split.
Fail-loud contract:
- a block naming a target absent from skillproj.toml fails the build
(a one-character typo must never silently drop content);
- unpaired, nested, or malformed directives fail the build;
- directive-looking lines inside fenced code blocks are literal text;
- every build asserts the output contains no live directives;
- output directories must be disjoint from the source tree and must
not contain the project root.
Usage:
python tools/skillbuild.py # build every target
python tools/skillbuild.py --target omp # build one target
python tools/skillbuild.py --check # validate only, no writes
Archive a build with tar:
tar -C skills -czf simplecadapi.tar.gz simplecadapi
"""
from __future__ import annotations
import argparse
import os
import re
import shutil
import sys
if sys.version_info >= (3, 11):
import tomllib
else: # pragma: no cover - Python 3.10
import tomli as tomllib # type: ignore[no-redef]
from dataclasses import dataclass
from pathlib import Path
CONFIG_NAME = "skillproj.toml"
NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
DIRECTIVE_PATTERN = re.compile(r"^\s*<!--\s*skill:(if|endif)\s*(.*?)\s*-->\s*$")
FENCE_PATTERN = re.compile(r"^\s{0,3}(?:`{3,}|~{3,})")
DENIED_DIR_NAMES = {"__pycache__"}
class SkillBuildError(Exception):
"""A fatal, user-facing build error."""
@dataclass(frozen=True)
class Condition:
"""A parsed skill:if expression: positive names and negated names."""
positives: tuple[str, ...]
negatives: tuple[str, ...]
@classmethod
def parse(
cls,
expression: str,
targets: "frozenset[str]",
where: str,
) -> "Condition":
positives: list[str] = []
negatives: list[str] = []
seen: set[str] = set()
for token in expression.split(","):
token = token.strip()
if not token:
raise SkillBuildError(
f"{where}: empty name in conditional expression {expression!r}"
)
negated = token.startswith("!")
name = token[1:] if negated else token
if not NAME_PATTERN.fullmatch(name):
raise SkillBuildError(f"{where}: invalid target name {name!r}")
if name not in targets:
declared = ", ".join(sorted(targets))
raise SkillBuildError(
f"{where}: unknown target {name!r} (declared: {declared})"
)
if name in seen:
raise SkillBuildError(
f"{where}: duplicate name {name!r} in expression {expression!r}"
)
seen.add(name)
if negated:
negatives.append(name)
else:
positives.append(name)
if not positives and not negatives:
raise SkillBuildError(
f"{where}: empty conditional expression {expression!r}"
)
return Condition(tuple(positives), tuple(negatives))
def includes(self, target: str) -> bool:
if target in self.negatives:
return False
return not self.positives or target in self.positives
def describe(self) -> str:
parts = list(self.positives) + [f"!{name}" for name in self.negatives]
return ",".join(parts)
@dataclass(frozen=True)
class ConditionalBlock:
"""One if..endif block; start/end are 0-based directive line indices."""
start: int
end: int
condition: Condition
@dataclass(frozen=True)
class SkillProject:
root: Path
name: str
source: Path
targets: tuple[str, ...]
outputs: dict
@dataclass(frozen=True)
class SourceFile:
path: Path
relative: Path
text: "str | None" # None -> binary, copied verbatim
blocks: "list[ConditionalBlock] | None" # None -> no directives
def find_project_root(start: Path) -> Path:
for candidate in (start.resolve(), *start.resolve().parents):
if (candidate / CONFIG_NAME).is_file():
return candidate
raise SkillBuildError(f"no {CONFIG_NAME} found in {start} or any parent")
def load_project(root: Path) -> SkillProject:
config_path = root / CONFIG_NAME
if not config_path.is_file():
raise SkillBuildError(f"missing {CONFIG_NAME} in {root}")
try:
data = tomllib.loads(config_path.read_text(encoding="utf-8"))
except tomllib.TOMLDecodeError as exc:
raise SkillBuildError(f"{config_path}: {exc}") from exc
skill = data.get("skill")
if not isinstance(skill, dict):
raise SkillBuildError(f"{config_path}: missing [skill] table")
name = skill.get("name")
if not isinstance(name, str) or not NAME_PATTERN.fullmatch(name):
raise SkillBuildError(
f"{config_path}: [skill] name must be lowercase words joined by single hyphens"
)
source_value = skill.get("source")
if not isinstance(source_value, str) or not source_value:
raise SkillBuildError(f"{config_path}: [skill] source is required")
source = (root / source_value).resolve()
if not source.is_dir():
raise SkillBuildError(f"{config_path}: source directory not found: {source}")
build = data.get("build")
if not isinstance(build, dict):
raise SkillBuildError(f"{config_path}: missing [build] table")
targets_value = build.get("targets")
if not isinstance(targets_value, list) or not targets_value:
raise SkillBuildError(
f"{config_path}: [build] targets must be a non-empty list"
)
targets = []
for item in targets_value:
if not isinstance(item, str) or not NAME_PATTERN.fullmatch(item):
raise SkillBuildError(f"{config_path}: invalid target name {item!r}")
if item in targets:
raise SkillBuildError(f"{config_path}: duplicate target {item!r}")
targets.append(item)
outputs_value = build.get("output")
if not isinstance(outputs_value, dict):
raise SkillBuildError(f"{config_path}: missing [build.output] table")
outputs = {}
for target in targets:
entry = outputs_value.get(target)
if not isinstance(entry, str) or not entry:
raise SkillBuildError(
f"{config_path}: [build.output] is missing target {target!r}"
)
outputs[target] = (root / entry).resolve()
_validate_output_paths(root.resolve(), source, outputs)
return SkillProject(root.resolve(), name, source, tuple(targets), outputs)
def _validate_output_paths(root: Path, source: Path, outputs: dict) -> None:
seen = {}
for target, output in outputs.items():
if output == root or output in root.parents:
raise SkillBuildError(
f"output for target {target!r} contains the project root: {output}"
)
if output == source or output in source.parents:
raise SkillBuildError(
f"output for target {target!r} contains the source tree: {output}"
)
if source in output.parents:
raise SkillBuildError(
f"output for target {target!r} is inside the source tree: {output}"
)
if output in seen:
raise SkillBuildError(
f"targets {seen[output]!r} and {target!r} share output {output}"
)
seen[output] = target
def _collect_blocks(
text: str,
targets: "frozenset[str]",
where: str,
) -> "list[ConditionalBlock] | None":
"""Fence-aware directive scan; validates structure and target names."""
lines = text.splitlines()
blocks: list[ConditionalBlock] = []
open_block: "tuple[int, Condition] | None" = None
in_fence = False
for index, line in enumerate(lines):
if in_fence:
if FENCE_PATTERN.match(line):
in_fence = False
continue
if FENCE_PATTERN.match(line):
in_fence = True
continue
match = DIRECTIVE_PATTERN.match(line)
if match is None:
continue
kind, expression = match.group(1), match.group(2)
location = f"{where}:{index + 1}"
if kind == "if":
if open_block is not None:
raise SkillBuildError(
f"{location}: nested skill:if (nesting is not supported; "
"split the file)"
)
open_block = (index, Condition.parse(expression, targets, location))
else:
if expression:
raise SkillBuildError(
f"{location}: skill:endif takes no expression"
)
if open_block is None:
raise SkillBuildError(
f"{location}: skill:endif without matching skill:if"
)
start, condition = open_block
blocks.append(ConditionalBlock(start, index, condition))
open_block = None
if open_block is not None:
raise SkillBuildError(
f"{where}:{open_block[0] + 1}: unclosed skill:if block"
)
return blocks or None
def compile_text(text: str, target: str, blocks: "list[ConditionalBlock]") -> str:
"""Resolve directives for one target; blank runs collapse to one line."""
lines = text.splitlines()
drop = set()
for block in blocks:
drop.add(block.start)
drop.add(block.end)
if not block.condition.includes(target):
drop.update(range(block.start + 1, block.end))
kept = [
line for index, line in enumerate(lines) if index not in drop
]
collapsed: list[str] = []
for line in kept:
if not line.strip() and collapsed and not collapsed[-1].strip():
continue
collapsed.append(line)
while collapsed and not collapsed[0].strip():
collapsed.pop(0)
while collapsed and not collapsed[-1].strip():
collapsed.pop()
if not collapsed:
return ""
return "\n".join(collapsed) + "\n"
def collect_source_files(
source: Path,
targets: "frozenset[str]",
root: Path,
) -> "list[SourceFile]":
"""Walk the source tree, validating every file's directives."""
files: list[SourceFile] = []
for dirpath, dirnames, filenames in os.walk(source):
dirnames[:] = sorted(
name for name in dirnames
if not name.startswith(".") and name not in DENIED_DIR_NAMES
)
for filename in sorted(filenames):
if filename.startswith("."):
continue
path = Path(dirpath) / filename
relative = path.relative_to(source)
where = str(path.relative_to(root))
raw = path.read_bytes()
try:
text = raw.decode("utf-8")
except UnicodeDecodeError:
files.append(SourceFile(path, relative, None, None))
continue
files.append(
SourceFile(path, relative, text, _collect_blocks(text, targets, where))
)
return files
def _frontmatter_name(text: str) -> "str | None":
lines = text.splitlines()
if not lines or lines[0].strip() != "---":
return None
for line in lines[1:]:
if line.strip() == "---":
return None
if line.startswith("name:"):
return line.split(":", 1)[1].strip()
return None
def verify_output(output: Path, project: SkillProject, target: str) -> None:
"""Assert the built tree contains no live directives and a sane SKILL.md."""
for path in sorted(p for p in output.rglob("*") if p.is_file()):
try:
text = path.read_bytes().decode("utf-8")
except UnicodeDecodeError:
continue
where = f"{path} (target {target!r})"
blocks = _collect_blocks(text, frozenset(project.targets), where)
if blocks:
raise SkillBuildError(
f"{where}:{blocks[0].start + 1}: directive survived compilation"
)
skill_md = output / "SKILL.md"
if skill_md.is_file():
declared = _frontmatter_name(skill_md.read_text(encoding="utf-8"))
if declared is not None and declared != project.name:
raise SkillBuildError(
f"target {target!r}: SKILL.md frontmatter name {declared!r} "
f"does not match [skill] name {project.name!r}"
)
def build_target(
project: SkillProject,
source_files: "list[SourceFile]",
target: str,
*,
quiet: bool = False,
) -> Path:
output = project.outputs[target]
if output.exists():
shutil.rmtree(output)
output.mkdir(parents=True)
included = 0
excluded = 0
for entry in source_files:
destination = output / entry.relative
destination.parent.mkdir(parents=True, exist_ok=True)
if entry.text is None or entry.blocks is None:
shutil.copyfile(entry.path, destination)
continue
destination.write_bytes(
compile_text(entry.text, target, entry.blocks).encode("utf-8")
)
for block in entry.blocks:
if block.condition.includes(target):
included += 1
else:
excluded += 1
verify_output(output, project, target)
if not quiet:
print(
f"built {target}: {len(source_files)} files -> {output} "
f"({included + excluded} blocks: {included} kept, {excluded} dropped)"
)
return output
def main(argv=None) -> int:
parser = argparse.ArgumentParser(
prog="skillbuild",
description="Compile a skill tree into per-target harness builds",
)
parser.add_argument(
"--project-root",
type=Path,
default=None,
help="project root containing skillproj.toml (default: search upward)",
)
parser.add_argument(
"--target",
action="append",
default=None,
help="build only this target (repeatable; default: all)",
)
parser.add_argument(
"--check",
action="store_true",
help="validate the tree without writing outputs",
)
args = parser.parse_args(argv)
try:
root = args.project_root.resolve() if args.project_root else find_project_root(Path.cwd())
project = load_project(root)
source_files = collect_source_files(
project.source, frozenset(project.targets), project.root
)
if args.check:
conditional = sum(1 for entry in source_files if entry.blocks)
print(
f"OK: {len(source_files)} files, {conditional} with conditional "
f"blocks, targets: {', '.join(project.targets)}"
)
return 0
selected = args.target or list(project.targets)
for target in selected:
if target not in project.outputs:
declared = ", ".join(project.targets)
raise SkillBuildError(
f"unknown --target {target!r} (declared: {declared})"
)
for target in selected:
build_target(project, source_files, target)
except SkillBuildError as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
return 0
if __name__ == "__main__":
sys.exit(main())
+63
View File
@@ -0,0 +1,63 @@
"""Build the bundled skill into a user-selected destination."""
from __future__ import annotations
import tempfile
from dataclasses import replace
from pathlib import Path
from typing import Any
from .compiler import (
SkillBuildError, SkillProject, _frontmatter_name, _validate_output_paths,
build_target, collect_source_files, load_project,
)
def bundled_project() -> SkillProject:
root = Path(__file__).parent / "resources"
if not (root / "skillproj.toml").is_file():
# Editable installs keep resources at their canonical checkout location.
root = Path(__file__).resolve().parents[3]
return load_project(root)
def _check_destination(output: Path, name: str, force: bool) -> None:
if output.is_symlink():
raise SkillBuildError(f"refusing symlink destination: {output}")
if not output.exists():
return
if not force:
raise SkillBuildError(f"destination exists: {output}; use --force to replace this skill")
marker = output / "SKILL.md"
if not output.is_dir() or not marker.is_file() or marker.is_symlink():
raise SkillBuildError(f"refusing to replace non-skill destination: {output}")
if _frontmatter_name(marker.read_text(encoding="utf-8")) != name:
raise SkillBuildError(f"refusing to replace destination with a different skill name: {output}")
def build_skill(*, project: SkillProject, target: str, output: Path,
force: bool = False) -> dict[str, Any]:
if target not in project.targets:
raise SkillBuildError(f"unknown target {target!r}; choose from: {', '.join(project.targets)}")
output = output.expanduser().absolute()
_check_destination(output, project.name, force)
output = output.resolve()
_validate_output_paths(project.root, project.source, {target: output})
source_files = collect_source_files(project.source, frozenset(project.targets), project.root)
output.parent.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory(prefix=".sca-skill-", dir=output.parent) as temporary:
stage = Path(temporary) / "build"
build_target(replace(project, outputs={target: stage}), source_files, target, quiet=True)
marker = stage / "SKILL.md"
if not marker.is_file() or _frontmatter_name(marker.read_text(encoding="utf-8")) != project.name:
raise SkillBuildError(f"source must contain SKILL.md declaring name: {project.name}")
_check_destination(output, project.name, force)
backup = Path(temporary) / "previous"
if output.exists():
output.rename(backup)
try:
stage.rename(output)
except OSError:
if backup.exists():
backup.rename(output)
raise
return {"name": project.name, "target": target, "output": str(output), "files": len(source_files)}
+126
View File
@@ -0,0 +1,126 @@
"""Runtime compilation, installation, and destination protection."""
from pathlib import Path
import pytest
from simplecadapi.cli import main, run
from simplecadapi.skill import cli
from simplecadapi.skill.compiler import SkillBuildError, load_project
@pytest.fixture
def project(tmp_path, monkeypatch):
root = tmp_path / "project"
source = root / "source"
source.mkdir(parents=True)
(source / "SKILL.md").write_text(
"---\nname: demo\n---\nshared\n<!-- skill:if zcode -->\nzcode-only\n<!-- skill:endif -->\n",
encoding="utf-8",
)
(source / "asset.bin").write_bytes(b"\xff\x00")
(root / "skillproj.toml").write_text(
'[skill]\nname="demo"\nsource="source"\n'
'[build]\ntargets=["zcode", "codex"]\n'
'[build.output]\nzcode="out/zcode"\ncodex="out/codex"\n',
encoding="utf-8",
)
result = load_project(root)
monkeypatch.setattr(cli, "bundled_project", lambda: result)
monkeypatch.setattr(Path, "home", lambda: tmp_path / "home")
monkeypatch.delenv("SCA_SKILLS_DIR", raising=False)
monkeypatch.delenv("SCA_ADDON_HOME", raising=False)
return result
def install_args(*extra):
return ["skill", "install", "--target", "zcode", *extra]
def test_targets(project):
report, code, printer = run(["skill", "targets"])
assert report == {"targets": ["zcode", "codex"]}
assert code == 0 and callable(printer)
printer(report)
@pytest.mark.parametrize("target, included", [("zcode", True), ("codex", False)])
def test_install_compiles_selected_target(project, tmp_path, target, included):
report, code, _ = run(
["skill", "install", "--target", target, "--skills-dir", str(tmp_path / "skills")]
)
output = tmp_path / "skills" / "demo"
text = (output / "SKILL.md").read_text()
assert ("zcode-only" in text) == included
assert "<!-- skill:" not in text
assert (output / "asset.bin").read_bytes() == b"\xff\x00"
assert Path(report["output"]) == output and code == 0
def test_install_default_location_without_init(project, tmp_path):
report, code, _ = run(install_args())
assert code == 0
assert Path(report["output"]) == tmp_path / "home/.agents/skills/demo"
assert not (tmp_path / "home/.sca").exists()
def test_install_location_precedence(project, tmp_path, monkeypatch):
home = tmp_path / "home/.sca"
home.mkdir(parents=True)
(home / "config.toml").write_text(f'skills_dir="{tmp_path / "configured"}"\n')
report, _, _ = run(install_args())
assert Path(report["output"]) == tmp_path / "configured/demo"
monkeypatch.setenv("SCA_SKILLS_DIR", str(tmp_path / "env"))
report, _, _ = run(install_args())
assert Path(report["output"]) == tmp_path / "env/demo"
report, _, _ = run(install_args("--skills-dir", str(tmp_path / "flag")))
assert Path(report["output"]) == tmp_path / "flag/demo"
def test_overwrite_requires_force_and_removes_stale_files(project, tmp_path):
skills_dir = tmp_path / "skills"
run(install_args("--skills-dir", str(skills_dir)))
output = skills_dir / "demo"
(output / "stale").write_text("old")
with pytest.raises(SkillBuildError, match="--force"):
run(install_args("--skills-dir", str(skills_dir)))
assert (output / "stale").exists()
run(install_args("--skills-dir", str(skills_dir), "--force"))
assert not (output / "stale").exists()
@pytest.mark.parametrize("kind", ["directory", "file", "other-skill", "symlink"])
def test_force_rejects_foreign_destinations(project, tmp_path, kind):
skills_dir = tmp_path / "skills"
output = skills_dir / "demo"
if kind == "file":
output.parent.mkdir(parents=True)
output.write_text("keep")
elif kind == "symlink":
output.parent.mkdir(parents=True)
output.symlink_to(project.source, target_is_directory=True)
else:
output.mkdir(parents=True)
if kind == "other-skill":
(output / "SKILL.md").write_text("---\nname: other\n---\n")
with pytest.raises(SkillBuildError, match="refusing"):
run(install_args("--skills-dir", str(skills_dir), "--force"))
assert output.exists()
def test_compilation_failure_preserves_destination(project, tmp_path):
skills_dir = tmp_path / "skills"
run(install_args("--skills-dir", str(skills_dir)))
output = skills_dir / "demo"
original = (output / "SKILL.md").read_bytes()
(project.source / "SKILL.md").write_text("<!-- skill:if typo -->\nx\n<!-- skill:endif -->\n")
with pytest.raises(SkillBuildError, match="unknown target"):
run(install_args("--skills-dir", str(skills_dir), "--force"))
assert (output / "SKILL.md").read_bytes() == original
def test_main_reports_unknown_target_without_traceback(project, tmp_path, capsys):
code = main(["skill", "install", "--target", "typo", "--skills-dir", str(tmp_path / "s")])
assert code == 2
error = capsys.readouterr().err
assert "unknown target" in error and "Traceback" not in error
assert not (tmp_path / "s").exists()
+15 -455
View File
@@ -1,458 +1,18 @@
#!/usr/bin/env python3
"""Compile a skill tree into per-target harness builds.
The tree layout is the filesystem under the source root configured in
skillproj.toml. This tool adds nothing, moves nothing, and invents no
layout. Its single job is conditional compilation:
<!-- skill:if omp,!claude -->
harness-specific text
<!-- skill:endif -->
A block is included in the build for target T iff T appears as a
positive name and not as a negated name. An expression with only
negations includes every target not negated. There is no else and no
nesting: complementary blocks express else, and a nesting need means
the file should be split.
Fail-loud contract:
- a block naming a target absent from skillproj.toml fails the build
(a one-character typo must never silently drop content);
- unpaired, nested, or malformed directives fail the build;
- directive-looking lines inside fenced code blocks are literal text;
- every build asserts the output contains no live directives;
- output directories must be disjoint from the source tree and must
not contain the project root.
Usage:
python tools/skillbuild.py # build every target
python tools/skillbuild.py --target omp # build one target
python tools/skillbuild.py --check # validate only, no writes
Archive a build with tar:
tar -C skills -czf simplecadapi.tar.gz simplecadapi
"""
from __future__ import annotations
import argparse
import os
import re
import shutil
import sys
if sys.version_info >= (3, 11):
import tomllib
else: # pragma: no cover - Python 3.10
import tomli as tomllib # type: ignore[no-redef]
from dataclasses import dataclass
from pathlib import Path
CONFIG_NAME = "skillproj.toml"
NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
DIRECTIVE_PATTERN = re.compile(r"^\s*<!--\s*skill:(if|endif)\s*(.*?)\s*-->\s*$")
FENCE_PATTERN = re.compile(r"^\s{0,3}(?:`{3,}|~{3,})")
DENIED_DIR_NAMES = {"__pycache__"}
class SkillBuildError(Exception):
"""A fatal, user-facing build error."""
@dataclass(frozen=True)
class Condition:
"""A parsed skill:if expression: positive names and negated names."""
positives: tuple[str, ...]
negatives: tuple[str, ...]
@classmethod
def parse(
cls,
expression: str,
targets: "frozenset[str]",
where: str,
) -> "Condition":
positives: list[str] = []
negatives: list[str] = []
seen: set[str] = set()
for token in expression.split(","):
token = token.strip()
if not token:
raise SkillBuildError(
f"{where}: empty name in conditional expression {expression!r}"
)
negated = token.startswith("!")
name = token[1:] if negated else token
if not NAME_PATTERN.fullmatch(name):
raise SkillBuildError(f"{where}: invalid target name {name!r}")
if name not in targets:
declared = ", ".join(sorted(targets))
raise SkillBuildError(
f"{where}: unknown target {name!r} (declared: {declared})"
)
if name in seen:
raise SkillBuildError(
f"{where}: duplicate name {name!r} in expression {expression!r}"
)
seen.add(name)
if negated:
negatives.append(name)
else:
positives.append(name)
if not positives and not negatives:
raise SkillBuildError(
f"{where}: empty conditional expression {expression!r}"
)
return Condition(tuple(positives), tuple(negatives))
def includes(self, target: str) -> bool:
if target in self.negatives:
return False
return not self.positives or target in self.positives
def describe(self) -> str:
parts = list(self.positives) + [f"!{name}" for name in self.negatives]
return ",".join(parts)
@dataclass(frozen=True)
class ConditionalBlock:
"""One if..endif block; start/end are 0-based directive line indices."""
start: int
end: int
condition: Condition
@dataclass(frozen=True)
class SkillProject:
root: Path
name: str
source: Path
targets: tuple[str, ...]
outputs: dict
@dataclass(frozen=True)
class SourceFile:
path: Path
relative: Path
text: "str | None" # None -> binary, copied verbatim
blocks: "list[ConditionalBlock] | None" # None -> no directives
def find_project_root(start: Path) -> Path:
for candidate in (start.resolve(), *start.resolve().parents):
if (candidate / CONFIG_NAME).is_file():
return candidate
raise SkillBuildError(f"no {CONFIG_NAME} found in {start} or any parent")
def load_project(root: Path) -> SkillProject:
config_path = root / CONFIG_NAME
if not config_path.is_file():
raise SkillBuildError(f"missing {CONFIG_NAME} in {root}")
try:
data = tomllib.loads(config_path.read_text(encoding="utf-8"))
except tomllib.TOMLDecodeError as exc:
raise SkillBuildError(f"{config_path}: {exc}") from exc
skill = data.get("skill")
if not isinstance(skill, dict):
raise SkillBuildError(f"{config_path}: missing [skill] table")
name = skill.get("name")
if not isinstance(name, str) or not NAME_PATTERN.fullmatch(name):
raise SkillBuildError(
f"{config_path}: [skill] name must be lowercase words joined by single hyphens"
)
source_value = skill.get("source")
if not isinstance(source_value, str) or not source_value:
raise SkillBuildError(f"{config_path}: [skill] source is required")
source = (root / source_value).resolve()
if not source.is_dir():
raise SkillBuildError(f"{config_path}: source directory not found: {source}")
build = data.get("build")
if not isinstance(build, dict):
raise SkillBuildError(f"{config_path}: missing [build] table")
targets_value = build.get("targets")
if not isinstance(targets_value, list) or not targets_value:
raise SkillBuildError(
f"{config_path}: [build] targets must be a non-empty list"
)
targets = []
for item in targets_value:
if not isinstance(item, str) or not NAME_PATTERN.fullmatch(item):
raise SkillBuildError(f"{config_path}: invalid target name {item!r}")
if item in targets:
raise SkillBuildError(f"{config_path}: duplicate target {item!r}")
targets.append(item)
outputs_value = build.get("output")
if not isinstance(outputs_value, dict):
raise SkillBuildError(f"{config_path}: missing [build.output] table")
outputs = {}
for target in targets:
entry = outputs_value.get(target)
if not isinstance(entry, str) or not entry:
raise SkillBuildError(
f"{config_path}: [build.output] is missing target {target!r}"
)
outputs[target] = (root / entry).resolve()
_validate_output_paths(root.resolve(), source, outputs)
return SkillProject(root.resolve(), name, source, tuple(targets), outputs)
def _validate_output_paths(root: Path, source: Path, outputs: dict) -> None:
seen = {}
for target, output in outputs.items():
if output == root or output in root.parents:
raise SkillBuildError(
f"output for target {target!r} contains the project root: {output}"
)
if output == source or output in source.parents:
raise SkillBuildError(
f"output for target {target!r} contains the source tree: {output}"
)
if source in output.parents:
raise SkillBuildError(
f"output for target {target!r} is inside the source tree: {output}"
)
if output in seen:
raise SkillBuildError(
f"targets {seen[output]!r} and {target!r} share output {output}"
)
seen[output] = target
def _collect_blocks(
text: str,
targets: "frozenset[str]",
where: str,
) -> "list[ConditionalBlock] | None":
"""Fence-aware directive scan; validates structure and target names."""
lines = text.splitlines()
blocks: list[ConditionalBlock] = []
open_block: "tuple[int, Condition] | None" = None
in_fence = False
for index, line in enumerate(lines):
if in_fence:
if FENCE_PATTERN.match(line):
in_fence = False
continue
if FENCE_PATTERN.match(line):
in_fence = True
continue
match = DIRECTIVE_PATTERN.match(line)
if match is None:
continue
kind, expression = match.group(1), match.group(2)
location = f"{where}:{index + 1}"
if kind == "if":
if open_block is not None:
raise SkillBuildError(
f"{location}: nested skill:if (nesting is not supported; "
"split the file)"
)
open_block = (index, Condition.parse(expression, targets, location))
else:
if expression:
raise SkillBuildError(
f"{location}: skill:endif takes no expression"
)
if open_block is None:
raise SkillBuildError(
f"{location}: skill:endif without matching skill:if"
)
start, condition = open_block
blocks.append(ConditionalBlock(start, index, condition))
open_block = None
if open_block is not None:
raise SkillBuildError(
f"{where}:{open_block[0] + 1}: unclosed skill:if block"
)
return blocks or None
def compile_text(text: str, target: str, blocks: "list[ConditionalBlock]") -> str:
"""Resolve directives for one target; blank runs collapse to one line."""
lines = text.splitlines()
drop = set()
for block in blocks:
drop.add(block.start)
drop.add(block.end)
if not block.condition.includes(target):
drop.update(range(block.start + 1, block.end))
kept = [
line for index, line in enumerate(lines) if index not in drop
]
collapsed: list[str] = []
for line in kept:
if not line.strip() and collapsed and not collapsed[-1].strip():
continue
collapsed.append(line)
while collapsed and not collapsed[0].strip():
collapsed.pop(0)
while collapsed and not collapsed[-1].strip():
collapsed.pop()
if not collapsed:
return ""
return "\n".join(collapsed) + "\n"
def collect_source_files(
source: Path,
targets: "frozenset[str]",
root: Path,
) -> "list[SourceFile]":
"""Walk the source tree, validating every file's directives."""
files: list[SourceFile] = []
for dirpath, dirnames, filenames in os.walk(source):
dirnames[:] = sorted(
name for name in dirnames
if not name.startswith(".") and name not in DENIED_DIR_NAMES
)
for filename in sorted(filenames):
if filename.startswith("."):
continue
path = Path(dirpath) / filename
relative = path.relative_to(source)
where = str(path.relative_to(root))
raw = path.read_bytes()
try:
text = raw.decode("utf-8")
except UnicodeDecodeError:
files.append(SourceFile(path, relative, None, None))
continue
files.append(
SourceFile(path, relative, text, _collect_blocks(text, targets, where))
)
return files
def _frontmatter_name(text: str) -> "str | None":
lines = text.splitlines()
if not lines or lines[0].strip() != "---":
return None
for line in lines[1:]:
if line.strip() == "---":
return None
if line.startswith("name:"):
return line.split(":", 1)[1].strip()
return None
def verify_output(output: Path, project: SkillProject, target: str) -> None:
"""Assert the built tree contains no live directives and a sane SKILL.md."""
for path in sorted(p for p in output.rglob("*") if p.is_file()):
try:
text = path.read_bytes().decode("utf-8")
except UnicodeDecodeError:
continue
where = f"{path.relative_to(project.root)} (target {target!r})"
blocks = _collect_blocks(text, frozenset(project.targets), where)
if blocks:
raise SkillBuildError(
f"{where}:{blocks[0].start + 1}: directive survived compilation"
)
skill_md = output / "SKILL.md"
if skill_md.is_file():
declared = _frontmatter_name(skill_md.read_text(encoding="utf-8"))
if declared is not None and declared != project.name:
raise SkillBuildError(
f"target {target!r}: SKILL.md frontmatter name {declared!r} "
f"does not match [skill] name {project.name!r}"
)
def build_target(
project: SkillProject,
source_files: "list[SourceFile]",
target: str,
) -> Path:
output = project.outputs[target]
if output.exists():
shutil.rmtree(output)
output.mkdir(parents=True)
included = 0
excluded = 0
for entry in source_files:
destination = output / entry.relative
destination.parent.mkdir(parents=True, exist_ok=True)
if entry.text is None or entry.blocks is None:
shutil.copyfile(entry.path, destination)
continue
destination.write_bytes(
compile_text(entry.text, target, entry.blocks).encode("utf-8")
)
for block in entry.blocks:
if block.condition.includes(target):
included += 1
else:
excluded += 1
verify_output(output, project, target)
print(
f"built {target}: {len(source_files)} files -> "
f"{output.relative_to(project.root)} "
f"({included + excluded} blocks: {included} kept, {excluded} dropped)"
)
return output
def main(argv=None) -> int:
parser = argparse.ArgumentParser(
prog="skillbuild",
description="Compile a skill tree into per-target harness builds",
)
parser.add_argument(
"--project-root",
type=Path,
default=None,
help="project root containing skillproj.toml (default: search upward)",
)
parser.add_argument(
"--target",
action="append",
default=None,
help="build only this target (repeatable; default: all)",
)
parser.add_argument(
"--check",
action="store_true",
help="validate the tree without writing outputs",
)
args = parser.parse_args(argv)
try:
root = args.project_root.resolve() if args.project_root else find_project_root(Path.cwd())
project = load_project(root)
source_files = collect_source_files(
project.source, frozenset(project.targets), project.root
)
if args.check:
conditional = sum(1 for entry in source_files if entry.blocks)
print(
f"OK: {len(source_files)} files, {conditional} with conditional "
f"blocks, targets: {', '.join(project.targets)}"
)
return 0
selected = args.target or list(project.targets)
for target in selected:
if target not in project.outputs:
declared = ", ".join(project.targets)
raise SkillBuildError(
f"unknown --target {target!r} (declared: {declared})"
)
for target in selected:
build_target(project, source_files, target)
except SkillBuildError as exc:
print(f"error: {exc}", file=sys.stderr)
return 1
return 0
"""Checkout entry point for the shared skill compiler."""
from simplecadapi.skill.compiler import (
Condition,
SkillBuildError,
SkillProject,
SourceFile,
build_target,
collect_source_files,
compile_text,
find_project_root,
load_project,
main,
verify_output,
)
if __name__ == "__main__":
sys.exit(main())
raise SystemExit(main())