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:
@@ -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
@@ -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
@@ -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,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)
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
@@ -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']}"
|
||||
)
|
||||
Executable
+460
@@ -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())
|
||||
@@ -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)}
|
||||
@@ -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
@@ -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())
|
||||
|
||||
Reference in New Issue
Block a user