iac-code 0.1.0__py3-none-any.whl

iac_code/skills/bundled/iac_aliyun/references/terraform-template.md

@@ -0,0 +1,101 @@
+# Terraform 模板最佳实践
+
+## 文件组织
+
+| 规模 | 组织方式 |
+|------|----------|
+| < 10 资源 | 单 `main.tf` |
+| 10-20 资源 | `provider.tf` + `variables.tf` + `main.tf` + `outputs.tf` |
+| > 20 资源 | 按资源类型拆分：`vpc.tf`、`ecs.tf`、`rds.tf` 等 |
+
+## 变量管理
+
+### 使用 validation 约束输入
+
+```hcl
+variable "env" {
+  type        = string
+  description = "环境标识"
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.env)
+    error_message = "env 必须为 dev、staging 或 prod"
+  }
+}
+```
+
+### 使用 locals 减少重复
+
+```hcl
+locals {
+  name_prefix = "${var.env}-${var.project}"
+  common_tags = {
+    Environment = var.env
+    ManagedBy   = "terraform"
+  }
+}
+```
+
+## Data Source
+
+使用 data source 查询动态信息，避免硬编码：
+
+```hcl
+data "alicloud_zones" "available" {
+  available_resource_creation = "VSwitch"
+}
+
+data "alicloud_images" "ubuntu" {
+  name_regex  = "^ubuntu_22"
+  owners      = "system"
+  most_recent = true
+}
+```
+
+## 命名约定
+
+- 资源名：`{env}-{product}-{role}`，如 `prod-ecs-web`
+- 变量名：蛇形命名，如 `instance_type`
+- 资源标识符：用途而非类型，如 `alicloud_instance.web` 而非 `alicloud_instance.instance1`
+
+## 执行公共命令
+
+`alicloud_ecs_commands` data source 查出 command_id，再用 `alicloud_ecs_invocation` 执行
+
+```hcl
+# 公共命令：先查 command_id
+data "alicloud_ecs_commands" "install_openclaw" {
+  name              = "ACS-ECS-InstallOpenClaw-for-linux.sh"
+  command_provider  = "AlibabaCloud"
+}
+
+# 再执行
+resource "alicloud_ecs_invocation" "install_openclaw" {
+  command_id  = data.alicloud_ecs_commands.install_openclaw.commands.0.id
+  instance_id = [alicloud_instance.web.id]
+}
+```
+
+## 与 ROS 集成
+
+ROS 支持通过 Terraform 类型模板部署。流程：
+
+1. 生成 Terraform 文件时，按 [template-parameters.md](template-parameters.md) 的「Terraform 模板的参数规范」：
+   - 变量 description 中写入 AssociationProperty、Label 等（JSON 格式）
+   - 在 tf 目录下创建 `.metadata` 文件定义 ParameterGroups
+2. 运行 `python ../scripts/tf2ros.py <terraform_dir> <output.yml>` 生成 ROS 模板文件
+   - 递归打包目录下所有文件（`.tf`、`.metadata`、`scripts/*.sh`、子目录任意文本文件等）到 Workspace
+   - 自动跳过 `.terraform/`、`.git/`、`__pycache__/` 目录及 `*.tfstate*` 文件
+3. 读取模板文件内容，调用 ros_stack(CreateStack) 部署
+
+## 文件函数的 path 参数限制（重要）
+
+`file`、`fileexists`、`fileset`、`filebase64` 的 path 参数受 ROS 严格校验，生成模板时必须遵守：
+
+- 必须是字面量字符串，不能引用变量
+- 第一个分词必须是 `${path.module}`、`${path.root}`、`${path.cwd}` 或 `${terraform.workspace}` 之一
+- 后续分词只允许字母、数字与 `-_.`，不允许为空、`.` 或 `..`（即不能用 `../` 跳出目录）
+- 引用的文件必须存在于 Workspace 中（即在传给 tf2ros.py 的目录里）
+
+## 其他模板结构限制
+
+Terraform 类型模板的其他结构性约束（provider 白名单、不支持的语法、变量类型等）以官方文档为准：<https://help.aliyun.com/zh/ros/user-guide/structure-of-terraform-templates>。ValidateTemplate 报错若指向模板结构问题，按报错信息对照该文档定位修复点。

iac_code/skills/bundled/iac_aliyun/scripts/tf2ros.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Convert a Terraform directory to a ROS Terraform-type template file."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import yaml
+
+
+class _BlockStr(str):
+    """String subclass that forces YAML block scalar (|) style."""
+
+
+def _block_str_representer(dumper: yaml.Dumper, data: _BlockStr) -> yaml.ScalarNode:
+    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
+
+
+yaml.add_representer(_BlockStr, _block_str_representer)
+
+
+# Directories that must never be bundled into Workspace.
+_SKIP_DIRS = {".terraform", ".git", "__pycache__"}
+# File suffixes that must never be bundled into Workspace.
+_SKIP_SUFFIXES = (".tfstate", ".tfstate.backup")
+
+
+def convert(tf_dir: str, output_path: str) -> None:
+    tf_path = Path(tf_dir)
+    if not tf_path.is_dir():
+        print(f"Error: {tf_dir} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    rel_paths: list[Path] = []
+    for root, dirs, files in os.walk(tf_path):
+        dirs[:] = [d for d in dirs if d not in _SKIP_DIRS]
+        for fname in files:
+            if fname.endswith(_SKIP_SUFFIXES):
+                continue
+            rel_paths.append(Path(root, fname).relative_to(tf_path))
+
+    workspace: dict[str, _BlockStr] = {}
+    for rel in sorted(rel_paths):
+        full = tf_path / rel
+        try:
+            text = full.read_text()
+        except UnicodeDecodeError:
+            print(f"Warning: skipping non-text file {rel.as_posix()}", file=sys.stderr)
+            continue
+        workspace[rel.as_posix()] = _BlockStr(text)
+
+    if not any(k.endswith(".tf") for k in workspace):
+        print(f"Error: no .tf files found in {tf_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    template: dict = {
+        "ROSTemplateFormatVersion": "2015-09-01",
+        "Transform": "Aliyun::OpenTofu-v1.8",
+        "Workspace": workspace,
+    }
+
+    out = Path(output_path)
+    if out.suffix in (".yml", ".yaml"):
+        out.write_text(yaml.dump(template, allow_unicode=True, default_flow_style=False, sort_keys=False))
+    else:
+        out.write_text(json.dumps(template, ensure_ascii=False, indent=2))
+
+    print(f"Template written to {out}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print(f"Usage: {sys.argv[0]} <terraform_dir> <output_file>", file=sys.stderr)
+        print("  output_file: .yml/.yaml for YAML, .json for JSON", file=sys.stderr)
+        sys.exit(1)
+    convert(sys.argv[1], sys.argv[2])

iac_code/skills/bundled/simplify.py

@@ -0,0 +1,28 @@
+"""Built-in simplify skill — review changed code for reuse, quality, and efficiency."""
+
+from iac_code.i18n import _
+from iac_code.skills.bundled import register_bundled_skill
+
+SIMPLIFY_PROMPT = """\
+Review the recently changed code for:
+
+1. **Reuse** — Are there existing functions, utilities, or patterns in the codebase that \
+could replace newly added code? Search broadly.
+2. **Quality** — Are there bugs, edge cases, or logic errors?
+3. **Efficiency** — Can the code be simplified without losing clarity?
+
+For each issue found:
+- Explain the problem
+- Show the fix (edit the file directly)
+
+If no issues are found, say so briefly.
+"""
+
+
+def register_simplify_skill() -> None:
+    register_bundled_skill(
+        name="simplify",
+        description=_("Review changed code for reuse, quality, and efficiency, then fix issues found."),
+        prompt=SIMPLIFY_PROMPT,
+        user_invocable=True,
+    )

iac_code/skills/discovery.py

@@ -0,0 +1,136 @@
+"""Skill discovery — scan filesystem sources and convert to PromptCommands."""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+from iac_code.commands.registry import PromptCommand
+from iac_code.skills.loader import load_skill_from_path
+from iac_code.skills.skill_definition import SkillDefinition
+from iac_code.types.skill_source import SkillSource
+
+
+def discover_all_skills(cwd: str) -> list[SkillDefinition]:
+    """Discover all available skills from all sources.
+
+    Load order (later entries override earlier with same name):
+    1. Bundled skills
+    2. User global skills (~/.iac-code/skills/)
+    3. Project local skills — skills/ (lower priority)
+    4. Project local skills — .iac-code/skills/ (higher priority, overrides same name)
+    """
+    from iac_code.skills.bundled import get_bundled_skills
+
+    skills: dict[str, SkillDefinition] = {}
+
+    # 1. Bundled skills
+    for skill in get_bundled_skills():
+        skills[skill.name] = skill
+
+    # 2. User global skills
+    user_skills_dir = Path.home() / ".iac-code" / "skills"
+    for skill in _scan_skills_dir(user_skills_dir):
+        skill.source = SkillSource.USER
+        skills[skill.name] = skill
+
+    # 3. Project local skills (two locations, .iac-code/skills/ has higher priority)
+    for project_dir in _find_project_skills_dirs(cwd):
+        for skill in _scan_skills_dir(project_dir):
+            skill.source = SkillSource.PROJECT
+            skills[skill.name] = skill
+
+    return list(skills.values())
+
+
+def _find_project_skills_dirs(cwd: str) -> list[Path]:
+    """Find project skills directories, searching up from cwd.
+
+    Returns directories in priority order (low -> high):
+    - skills/           (root-level, lower priority)
+    - .iac-code/skills/ (config-level, higher priority)
+    """
+    result: list[Path] = []
+    current = Path(cwd).resolve()
+    while True:
+        # Lower priority: skills/
+        bare = current / "skills"
+        if bare.is_dir():
+            result.append(bare)
+        # Higher priority: .iac-code/skills/
+        dotdir = current / ".iac-code" / "skills"
+        if dotdir.is_dir():
+            result.append(dotdir)
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    return result
+
+
+def _scan_skills_dir(skills_dir: Path) -> list[SkillDefinition]:
+    """Scan a skills directory for skill files."""
+    if not skills_dir.is_dir():
+        return []
+
+    skills: list[SkillDefinition] = []
+    seen_real_paths: set[str] = set()
+
+    for entry in skills_dir.iterdir():
+        real_path = str(entry.resolve())
+        if real_path in seen_real_paths:
+            continue
+        seen_real_paths.add(real_path)
+
+        if entry.is_dir():
+            # Directory format: skill-name/SKILL.md
+            skill_file = entry / "SKILL.md"
+            if skill_file.is_file():
+                skill = load_skill_from_path(skill_file, skill_name=entry.name)
+                if skill:
+                    skill.skill_root = str(entry)
+                    skills.append(skill)
+        elif entry.suffix == ".md" and entry.name != "SKILL.md":
+            # Single file format: skill-name.md
+            skill = load_skill_from_path(entry, skill_name=entry.stem)
+            if skill:
+                skills.append(skill)
+
+    return skills
+
+
+def skill_to_command(skill: SkillDefinition) -> PromptCommand:
+    """Convert a SkillDefinition to a PromptCommand."""
+    return PromptCommand(
+        name=skill.name,
+        description=skill.description,
+        skill=skill,
+        source=skill.source,
+    )
+
+
+class DynamicSkillTracker:
+    """Tracks file access and dynamically activates path-matched skills."""
+
+    def __init__(self) -> None:
+        self._accessed_paths: set[str] = set()
+        self._activated_skills: dict[str, SkillDefinition] = {}
+
+    def on_file_accessed(self, file_path: str, all_skills: list[SkillDefinition]) -> None:
+        """Called when a file is accessed by a tool. Checks path-matched skills."""
+        self._accessed_paths.add(file_path)
+        for skill in all_skills:
+            if skill.name in self._activated_skills:
+                continue
+            if skill.frontmatter.paths and self._matches_any_pattern(file_path, skill.frontmatter.paths):
+                self._activated_skills[skill.name] = skill
+
+    def get_activated_skills(self) -> list[SkillDefinition]:
+        return list(self._activated_skills.values())
+
+    @staticmethod
+    def _matches_any_pattern(file_path: str, patterns: list[str]) -> bool:
+        for pattern in patterns:
+            if fnmatch.fnmatch(file_path, pattern):
+                return True
+        return False

iac_code/skills/frontmatter.py

@@ -0,0 +1,119 @@
+"""YAML Frontmatter parsing for skill markdown files."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+FRONTMATTER_REGEX = re.compile(r"^---\s*\n([\s\S]*?)---\s*\n?")
+
+# YAML special characters that need auto-quoting
+YAML_SPECIAL_CHARS = set("{}[]*&#!|>%@")
+
+
+@dataclass
+class SkillFrontmatter:
+    """Parsed skill frontmatter metadata."""
+
+    name: str = ""
+    description: str = ""
+    descriptions: dict[str, str] = field(default_factory=dict)
+    allowed_tools: list[str] = field(default_factory=list)
+    when_to_use: str = ""
+    argument_hint: str = ""
+    arguments: list[str] = field(default_factory=list)
+    user_invocable: bool = True
+    model: str = "inherit"
+    effort: str = ""
+    context: str = "inline"  # "inline" | "fork"
+    agent: str = "general-purpose"
+    paths: list[str] = field(default_factory=list)
+
+
+def parse_frontmatter(markdown: str) -> tuple[SkillFrontmatter, str]:
+    """Parse YAML frontmatter from a skill markdown file.
+
+    Returns:
+        (frontmatter, content) - parsed metadata and remaining markdown body.
+    """
+    match = FRONTMATTER_REGEX.match(markdown)
+    if not match:
+        return SkillFrontmatter(), markdown
+
+    frontmatter_text = match.group(1)
+    content = markdown[match.end() :]
+
+    # First parse attempt
+    data = _parse_yaml_safe(frontmatter_text)
+
+    # If failed, auto-quote problematic values and retry
+    if data is None:
+        quoted_text = _quote_problematic_values(frontmatter_text)
+        data = _parse_yaml_safe(quoted_text)
+
+    if data is None:
+        return SkillFrontmatter(), content
+
+    return _data_to_frontmatter(data), content
+
+
+def _parse_yaml_safe(text: str) -> dict[str, Any] | None:
+    """Safely parse YAML text, returning None on failure."""
+    try:
+        result = yaml.safe_load(text)
+        return result if isinstance(result, dict) else None
+    except yaml.YAMLError:
+        return None
+
+
+def _quote_problematic_values(text: str) -> str:
+    """Auto-quote values containing special YAML characters (e.g., glob patterns)."""
+    lines = []
+    for line in text.split("\n"):
+        if ":" in line and not line.strip().startswith("-"):
+            key, _, value = line.partition(":")
+            value = value.strip()
+            if (
+                value
+                and any(c in value for c in YAML_SPECIAL_CHARS)
+                and not (value.startswith('"') or value.startswith("'"))
+            ):
+                line = f'{key}: "{value}"'
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _data_to_frontmatter(data: dict[str, Any]) -> SkillFrontmatter:
+    """Convert raw YAML dict to SkillFrontmatter dataclass."""
+    from iac_code.i18n import get_current_language
+
+    fm = SkillFrontmatter()
+    fm.name = data.get("name", "")
+    fm.description = data.get("description", "")
+
+    # Support localized descriptions via "descriptions" dict
+    descriptions = data.get("descriptions")
+    if isinstance(descriptions, dict):
+        fm.descriptions = {str(k): str(v) for k, v in descriptions.items()}
+        lang = get_current_language()
+        if lang in fm.descriptions:
+            fm.description = fm.descriptions[lang]
+
+    # allowed_tools: supports str or list[str]
+    tools = data.get("allowed_tools", [])
+    fm.allowed_tools = [tools] if isinstance(tools, str) else list(tools or [])
+
+    fm.when_to_use = data.get("when_to_use", "")
+    fm.argument_hint = data.get("argument_hint", "")
+    fm.arguments = list(data.get("arguments", []))
+    fm.user_invocable = data.get("user_invocable", True)
+    fm.model = data.get("model", "inherit")
+    fm.effort = data.get("effort", "")
+    fm.context = data.get("context", "inline")
+    fm.agent = data.get("agent", "general-purpose")
+    fm.paths = list(data.get("paths", []))
+
+    return fm

iac_code/skills/listing.py

@@ -0,0 +1,92 @@
+"""Skill listing generation for system prompt injection."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from iac_code.types.skill_source import SkillSource
+
+if TYPE_CHECKING:
+    from iac_code.commands.registry import PromptCommand
+
+SKILL_BUDGET_CONTEXT_PERCENT = 0.01
+MAX_LISTING_DESC_CHARS = 250
+DEFAULT_CHAR_BUDGET = 8_000  # 200K * 4 chars/token * 1%
+
+
+def get_char_budget(context_window_tokens: int | None = None) -> int:
+    if context_window_tokens:
+        return int(context_window_tokens * 4 * SKILL_BUDGET_CONTEXT_PERCENT)
+    return DEFAULT_CHAR_BUDGET
+
+
+def build_skill_listing(
+    skills: list[PromptCommand],
+    context_window_tokens: int | None = None,
+) -> str:
+    """Build the skill listing string for injection into the system prompt.
+
+    Truncation strategy:
+    1. Try full description + when_to_use for all skills
+    2. If over budget: bundled skills keep full description; others truncated proportionally
+    3. Extreme case: other skills show name only
+    """
+    if not skills:
+        return ""
+
+    budget = get_char_budget(context_window_tokens)
+
+    # Separate bundled and other skills
+    bundled = [s for s in skills if s.source == SkillSource.BUNDLED]
+    others = [s for s in skills if s.source != SkillSource.BUNDLED]
+
+    # Try full descriptions
+    lines = _format_full(bundled + others)
+    total = sum(len(line) for line in lines)
+
+    if total <= budget:
+        return _assemble(lines)
+
+    # Over budget: bundled keep full, others get proportional budget
+    bundled_lines = _format_full(bundled)
+    bundled_cost = sum(len(line) for line in bundled_lines)
+    remaining_budget = budget - bundled_cost
+
+    if remaining_budget <= 0:
+        other_lines = [f"- {s.name}" for s in others]
+    else:
+        per_skill_budget = remaining_budget // max(len(others), 1)
+        other_lines = _format_truncated(others, per_skill_budget)
+
+    return _assemble(bundled_lines + other_lines)
+
+
+def _format_full(skills: list[PromptCommand]) -> list[str]:
+    lines = []
+    for s in skills:
+        desc = s.description
+        if s.when_to_use:
+            desc += f"\n{s.when_to_use}"
+        if len(desc) > MAX_LISTING_DESC_CHARS:
+            desc = desc[: MAX_LISTING_DESC_CHARS - 3] + "..."
+        lines.append(f"- {s.name}: {desc}")
+    return lines
+
+
+def _format_truncated(skills: list[PromptCommand], per_skill_budget: int) -> list[str]:
+    lines = []
+    for s in skills:
+        desc = s.description
+        max_desc = per_skill_budget - len(s.name) - 4  # "- name: "
+        if max_desc <= 0:
+            lines.append(f"- {s.name}")
+        elif len(desc) > max_desc:
+            lines.append(f"- {s.name}: {desc[: max_desc - 3]}...")
+        else:
+            lines.append(f"- {s.name}: {desc}")
+    return lines
+
+
+def _assemble(lines: list[str]) -> str:
+    header = "The following skills are available for use with the Skill tool:\n"
+    return header + "\n".join(lines)

iac_code/skills/loader.py

@@ -0,0 +1,42 @@
+"""Load SkillDefinition from disk."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loguru import logger
+
+from iac_code.skills.frontmatter import parse_frontmatter
+from iac_code.skills.skill_definition import SkillDefinition
+
+
+def load_skill_from_path(file_path: Path, skill_name: str) -> SkillDefinition | None:
+    """Load a skill from a markdown file.
+
+    Args:
+        file_path: Path to the .md file.
+        skill_name: Default name (from directory or filename).
+
+    Returns:
+        SkillDefinition or None if the file cannot be read.
+    """
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        logger.warning("Failed to read skill file %s: %s", file_path, e)
+        return None
+
+    frontmatter, content = parse_frontmatter(text)
+
+    # Use frontmatter name if provided, otherwise use the filesystem-derived name
+    name = frontmatter.name or skill_name
+    description = frontmatter.description or ""
+
+    return SkillDefinition(
+        name=name,
+        description=description,
+        frontmatter=frontmatter,
+        content=content,
+        file_path=str(file_path),
+        content_length=len(content),
+    )

iac_code/skills/processor.py

@@ -0,0 +1,81 @@
+"""Unified skill processing — shared by slash commands and SkillTool."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from iac_code.skills.skill_definition import SkillContext
+
+
+@dataclass
+class ProcessedSkillResult:
+    """Unified result of processing a skill (from either slash command or SkillTool).
+
+    Both execution paths produce this same structure, ensuring identical behavior.
+    """
+
+    prompt_content: str
+    skill_name: str
+    new_messages: list[dict[str, Any]]
+    context_modifier: Callable[[dict], dict] | None = None
+    is_fork: bool = False
+
+
+async def process_prompt_command(
+    command: Any,
+    args: str,
+    *,
+    session_id: str = "",
+) -> ProcessedSkillResult:
+    """Unified skill processing — called by BOTH slash commands AND SkillTool.
+
+    1. Render skill prompt (argument substitution + variable replacement + shell execution)
+    2. Wrap as <skill-name> tagged message
+    3. Build context_modifier (allowed_tools / model / effort)
+    """
+    skill = command.skill
+    if skill is None:
+        raise ValueError(f"Command '{command.name}' is not a skill")
+
+    skill_context = SkillContext(
+        cwd=os.getcwd(),
+        session_id=session_id,
+        skill_dir=skill.skill_root or "",
+        skill_root=skill.skill_root or "",
+    )
+
+    # Step 1: Render prompt
+    prompt_content = await skill.get_prompt(args, skill_context)
+
+    # Step 2: Wrap as tagged message
+    tagged_content = f"<skill-name>{command.name}</skill-name>\n\n{prompt_content}"
+    new_messages = [{"role": "user", "content": tagged_content}]
+
+    # Step 3: Build context_modifier
+    allowed_tools = skill.allowed_tools
+    model_override = skill.model_override
+    effort_override = skill.effort_override
+
+    context_modifier = None
+    if allowed_tools or (model_override and model_override != "inherit") or effort_override:
+
+        def context_modifier(ctx: dict) -> dict:
+            modified = {**ctx}
+            if allowed_tools:
+                existing = modified.get("allowed_tool_rules", [])
+                modified["allowed_tool_rules"] = existing + allowed_tools
+            if model_override and model_override != "inherit":
+                modified["model_override"] = model_override
+            if effort_override:
+                modified["effort_override"] = effort_override
+            return modified
+
+    return ProcessedSkillResult(
+        prompt_content=prompt_content,
+        skill_name=command.name,
+        new_messages=new_messages,
+        context_modifier=context_modifier,
+        is_fork=(skill.context_mode == "fork"),
+    )