@softspark/ai-toolkit 4.24.0 → 4.25.0

package/scripts/generate_cline_hooks.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
+"""Generate Cline CLI and extension-compatible hook executables."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from secure_fs import (
+    SecureDestination,
+    SecureTransaction,
+    lexical_absolute,
+    nearest_existing_root,
+    run_secure_transaction,
+)
+
+
+HOOK_EVENTS = (
+    "TaskStart",
+    "TaskResume",
+    "TaskCancel",
+    "TaskComplete",
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "PreCompact",
+)
+MANAGED_MARKER = "# ai-toolkit-managed: cline-hook"
+
+
+HOOK_SOURCE = '''#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# ai-toolkit-managed: cline-hook
+"""Self-contained ai-toolkit adapter for one native Cline hook event."""
+
+from __future__ import annotations
+
+import json
+import re
+import signal
+import sys
+from pathlib import Path
+from typing import Any
+
+
+MAX_INPUT_BYTES = 1024 * 1024
+MAX_RUNTIME_SECONDS = 4
+EVENTS = {
+    "TaskStart",
+    "TaskResume",
+    "TaskCancel",
+    "TaskComplete",
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "PreCompact",
+}
+COMMAND_TOOLS = {
+    "execute_command",
+    "run_command",
+    "run_commands",
+    "bash",
+    "shell",
+}
+DESTRUCTIVE_PATTERNS = tuple(
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"(?:^|[;&|]\\s*)rm\\s+(?:-[rRf]+|--recursive|--force)\\b",
+        r"\\bsudo\\s+rm\\b",
+        r"\\bgit\\s+reset\\s+--hard\\b",
+        r"\\bgit\\s+clean\\s+-[^\\s]*f",
+        r"\\bgit\\s+push\\s+.*(?:--force(?:\\s|$)|-f(?:\\s|$))",
+        r"\\b(?:mkfs|shred)\\b",
+        r"\\bdd\\s+if=.+\\s+of=/dev/",
+        r"\\bDROP\\s+(?:DATABASE|SCHEMA|TABLE)\\b",
+        r"\\bTRUNCATE\\s+(?:TABLE\\s+)?\\S+",
+        r"\\bterraform\\s+destroy\\b",
+        r"\\bkubectl\\s+delete\\s+(?:namespace|ns|all|node)\\b",
+    )
+)
+CONTEXT_BY_EVENT = {
+    "TaskStart": (
+        "Follow repository instructions, keep changes scoped, and verify before "
+        "claiming completion."
+    ),
+    "TaskResume": (
+        "Reconfirm the current objective, pending work, and repository state "
+        "before continuing."
+    ),
+    "UserPromptSubmit": (
+        "For technical work, search the project knowledge base first and cite "
+        "the source paths used."
+    ),
+    "PreCompact": (
+        "Preserve the objective, completed and pending work, modified files, "
+        "decisions, and verification evidence during compaction."
+    ),
+}
+
+
+def _timeout(_signum: int, _frame: object) -> None:
+    raise TimeoutError("Cline hook exceeded its deadline")
+
+
+def _read_payload() -> dict[str, Any]:
+    raw = sys.stdin.buffer.read(MAX_INPUT_BYTES + 1)
+    if len(raw) > MAX_INPUT_BYTES:
+        raise ValueError("Cline hook payload exceeds 1 MiB")
+    if not raw.strip():
+        return {}
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError("Cline hook payload must be an object")
+    return value
+
+
+def _pre_tool_use(payload: dict[str, Any]) -> dict[str, Any]:
+    data = payload.get("preToolUse")
+    if not isinstance(data, dict):
+        return {"cancel": True, "errorMessage": "Invalid preToolUse payload."}
+    tool = data.get("toolName")
+    parameters = data.get("parameters")
+    if not isinstance(tool, str) or not tool:
+        return {"cancel": True, "errorMessage": "Invalid toolName value."}
+    if not isinstance(parameters, dict):
+        return {"cancel": True, "errorMessage": "Invalid command parameters."}
+    if tool.lower() not in COMMAND_TOOLS:
+        return {"cancel": False}
+    commands = parameters.get("commands") if tool.lower() == "run_commands" else None
+    if commands is None:
+        commands = [parameters.get("command")]
+    if (
+        not isinstance(commands, list)
+        or not commands
+        or any(
+            not isinstance(command, str) or not command.strip()
+            for command in commands
+        )
+    ):
+        return {"cancel": True, "errorMessage": "Invalid command value."}
+    if any(
+        pattern.search(command)
+        for command in commands
+        for pattern in DESTRUCTIVE_PATTERNS
+    ):
+        return {
+            "cancel": True,
+            "errorMessage": "Potentially destructive command requires explicit user approval.",
+        }
+    return {"cancel": False}
+
+
+def respond(event: str, payload: dict[str, Any]) -> dict[str, Any]:
+    if event == "PreToolUse":
+        return _pre_tool_use(payload)
+    if event in CONTEXT_BY_EVENT:
+        return {
+            "cancel": False,
+            "contextModification": CONTEXT_BY_EVENT[event],
+            "errorMessage": "",
+        }
+    return {"cancel": False}
+
+
+def main() -> int:
+    event = Path(sys.argv[0]).name
+    if event not in EVENTS:
+        print("Unsupported Cline hook event", file=sys.stderr)
+        return 2
+    signal.signal(signal.SIGALRM, _timeout)
+    signal.alarm(MAX_RUNTIME_SECONDS)
+    try:
+        result = respond(event, _read_payload())
+        print(json.dumps(result, separators=(",", ":"), sort_keys=True))
+        return 0
+    except (json.JSONDecodeError, TimeoutError, ValueError) as error:
+        print(
+            json.dumps(
+                {
+                    "cancel": True,
+                    "errorMessage": f"Cline hook input rejected: {error}",
+                },
+                separators=(",", ":"),
+                sort_keys=True,
+            )
+        )
+        return 0
+    finally:
+        signal.alarm(0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+'''
+
+
+def _hook_paths(target_dir: Path, hooks_root: Path | None = None) -> list[Path]:
+    hooks_dir = hooks_root or target_dir / ".cline" / "hooks"
+    return [hooks_dir / event for event in HOOK_EVENTS]
+
+
+def _default_hook_roots(target: Path) -> list[Path]:
+    roots = [target / ".cline" / "hooks"]
+    compatibility_root = target / ".clinerules"
+    if compatibility_root.is_symlink():
+        raise RuntimeError(
+            f"Unsafe symlinked Cline hooks ancestor: {compatibility_root}"
+        )
+    if not compatibility_root.is_file():
+        roots.append(compatibility_root / "hooks")
+    return roots
+
+
+def _stale_candidates(hooks_dir: Path) -> list[Path]:
+    if not hooks_dir.exists():
+        return []
+    if hooks_dir.is_symlink() or not hooks_dir.is_dir():
+        raise RuntimeError(f"Unsafe Cline hooks directory: {hooks_dir}")
+    active_names = set(HOOK_EVENTS)
+    return sorted(
+        (
+            path
+            for path in hooks_dir.iterdir()
+            if path.name not in active_names
+            and not path.is_symlink()
+            and path.is_file()
+        ),
+        key=lambda path: path.name,
+    )
+
+
+def _reject_symlink_ancestors(target: Path, output_root: Path) -> None:
+    try:
+        relative = output_root.relative_to(target)
+    except ValueError as error:
+        raise RuntimeError(
+            f"Cline hooks root escapes target directory: {output_root}"
+        ) from error
+    current = target
+    for part in relative.parts:
+        current = current / part
+        if current.is_symlink():
+            raise RuntimeError(f"Unsafe symlinked Cline hooks ancestor: {current}")
+        if not current.exists():
+            break
+        if not current.is_dir():
+            raise RuntimeError(f"Unsafe non-directory Cline hooks ancestor: {current}")
+
+
+def generate(target_dir: Path, *, hooks_root: Path | None = None) -> Path:
+    """Write all eight Cline hook executables atomically.
+
+    ``hooks_root`` selects a documented compatibility root while keeping
+    ``target_dir`` as the trusted filesystem boundary. Without an override,
+    project hooks are dual-emitted to ``.cline/hooks`` and
+    ``.clinerules/hooks`` unless a legacy ``.clinerules`` file occupies the
+    compatibility path.
+    """
+    target = lexical_absolute(target_dir)
+    if target.is_symlink() or not target.is_dir():
+        raise RuntimeError(f"Unsafe Cline target directory: {target}")
+    output_roots = (
+        [lexical_absolute(hooks_root)]
+        if hooks_root is not None
+        else _default_hook_roots(target)
+    )
+    for output_root in output_roots:
+        _reject_symlink_ancestors(target, output_root)
+    root = nearest_existing_root(target)
+    active_destinations = [
+        SecureDestination(path, root, f"Cline {path.name} hook")
+        for output_root in output_roots
+        for path in _hook_paths(target, output_root)
+    ]
+    stale_destinations = [
+        SecureDestination(path, root, f"Cline stale {path.name} hook")
+        for output_root in output_roots
+        for path in _stale_candidates(output_root)
+    ]
+    destinations = active_destinations + stale_destinations
+
+    def apply(transaction: SecureTransaction) -> None:
+        for destination in active_destinations:
+            content = transaction.initial_content(destination)
+            if content is not None and MANAGED_MARKER.encode() not in content[:256]:
+                raise RuntimeError(
+                    f"Refusing user-owned Cline hook: {destination.path}"
+                )
+        for destination in active_destinations:
+            transaction.atomic_write(destination, HOOK_SOURCE.encode(), 0o755)
+        for destination in stale_destinations:
+            content = transaction.initial_content(destination)
+            if content is not None and MANAGED_MARKER.encode() in content[:256]:
+                transaction.unlink(destination)
+
+    run_secure_transaction(destinations, apply)
+    return output_roots[0]
+
+
+def generate_global(home_dir: Path) -> Path:
+    """Write hooks below Cline CLI's global ``~/.cline/hooks`` root."""
+    home = lexical_absolute(home_dir)
+    return generate(home, hooks_root=home / ".cline" / "hooks")
+
+
+def generate_extension_global(home_dir: Path) -> Path:
+    """Write extension-compatible hooks below ``~/Documents/Cline/Hooks``."""
+    home = lexical_absolute(home_dir)
+    return generate(home, hooks_root=home / "Documents" / "Cline" / "Hooks")
+
+
+def cleanup(target_dir: Path, *, hooks_root: Path | None = None) -> None:
+    """Remove only ai-toolkit-managed hook files from a Cline target."""
+    target = lexical_absolute(target_dir)
+    if target.is_symlink() or not target.is_dir():
+        return
+    hook_roots = (
+        [lexical_absolute(hooks_root)]
+        if hooks_root is not None
+        else _default_hook_roots(target)
+    )
+    for hooks_dir in hook_roots:
+        _reject_symlink_ancestors(target, hooks_dir)
+    root = nearest_existing_root(target)
+    candidates = [
+        path
+        for hooks_dir in hook_roots
+        if hooks_dir.is_dir()
+        for path in _hook_paths(target, hooks_dir) + _stale_candidates(hooks_dir)
+    ]
+    destinations = [
+        SecureDestination(path, root, f"Cline {path.name} hook")
+        for path in candidates
+        if path.is_file() and not path.is_symlink()
+    ]
+    if not destinations:
+        return
+
+    def apply(transaction: SecureTransaction) -> None:
+        for destination in destinations:
+            content = transaction.initial_content(destination)
+            if content is not None and MANAGED_MARKER.encode() in content[:256]:
+                transaction.unlink(destination)
+
+    run_secure_transaction(destinations, apply)
+
+
+def discover(target_dir: Path, *, hooks_root: Path | None = None) -> int:
+    """Return the number of ai-toolkit-managed Cline hook files."""
+    target = lexical_absolute(target_dir)
+    if target.is_symlink() or not target.is_dir():
+        raise RuntimeError(f"Unsafe Cline target directory: {target}")
+    roots = (
+        [lexical_absolute(hooks_root)]
+        if hooks_root is not None
+        else _default_hook_roots(target)
+    )
+    for root in roots:
+        _reject_symlink_ancestors(target, root)
+    count = 0
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for path in root.iterdir():
+            if path.is_symlink() or not path.is_file():
+                continue
+            try:
+                with path.open("rb") as handle:
+                    content = handle.read(256)
+            except OSError:
+                continue
+            if MANAGED_MARKER.encode() in content:
+                count += 1
+    return count
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+    roots = _default_hook_roots(lexical_absolute(target))
+    print(f"Generated: {', '.join(map(str, roots))} ({len(HOOK_EVENTS)} hooks each)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_cline_rules.py

@@ -3,11 +3,11 @@
 # Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
 # Source: https://github.com/softspark/ai-toolkit
 
-"""Generate ``.clinerules/*.md`` files and companion workflows for Cline.
+"""Generate native Cline rules plus extension-compatible rule files.
 
-Cline reads rules from the ``.clinerules/`` directory (since Cline 3.7).
-Each ``.md`` file inside is automatically loaded. The legacy single-file
-``.clinerules`` format is replaced by this directory.
+Cline CLI/SDK reads ``.cline/rules/*.md``. The IDE extension also reads the
+``.clinerules/*.md`` compatibility surface. A user-owned legacy single-file
+``.clinerules`` is preserved byte-identically while native rules are emitted.
 
 This generator also produces:
   * ``.clinerules/workflows/*.md`` — project-local workflow files that
@@ -36,9 +36,15 @@ from dir_rules_shared import (
     STANDARD_WORKFLOWS,
     build_language_rules,
     build_registered_rules,
-    cleanup_stale,
+    rule_scope,
     rule_testing,
-    write_rules,
+)
+from secure_fs import (
+    SecureDestination,
+    SecureTransaction,
+    lexical_absolute,
+    nearest_existing_root,
+    run_secure_transaction,
 )
 
 
@@ -78,25 +84,114 @@ def _wrap_language_rule(raw: str, lang: str) -> str:
     return _conditional(raw, globs)
 
 
-def generate(target_dir: Path, *,
-             language_modules: list[str] | None = None,
-             rules_dir: Path | None = None,
-             cleanup: bool = True,
-             emit_workflows: bool = True,
-             managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,),
-             output_root: Path | None = None) -> None:
+def _trusted_target(target_dir: Path) -> tuple[Path, Path]:
+    target = lexical_absolute(target_dir)
+    if target.is_symlink() or not target.is_dir():
+        raise RuntimeError(f"Unsafe Cline target directory: {target}")
+    return target, nearest_existing_root(target)
+
+
+def _output_root(target: Path, root: Path) -> Path:
+    output = lexical_absolute(root)
+    try:
+        output.relative_to(target)
+    except ValueError as error:
+        raise RuntimeError(f"Cline rules root escapes target: {output}") from error
+    return output
+
+
+def _preflight_roots(target: Path, roots: list[Path], trusted_root: Path) -> None:
+    probes = [
+        SecureDestination(
+            root / ".ai-toolkit-secure-probe",
+            trusted_root,
+            f"Cline {root.relative_to(target)} ancestry",
+        )
+        for root in roots
+    ]
+    transaction = SecureTransaction(probes)
+    transaction.close()
+
+
+def _managed_paths(root: Path, scopes: set[str]) -> list[Path]:
+    if not root.exists():
+        return []
+    if root.is_symlink() or not root.is_dir():
+        raise RuntimeError(f"Unsafe Cline rules directory: {root}")
+    return sorted(
+        path for path in root.iterdir() if rule_scope(path.name) in scopes
+    )
+
+
+def _render_rules(rules: dict[str, callable]) -> dict[str, bytes]:
+    return {
+        filename: content_fn().encode("utf-8")
+        for filename, content_fn in rules.items()
+    }
+
+
+def _write_transaction(
+    target: Path,
+    trusted_root: Path,
+    outputs: dict[Path, dict[str, bytes]],
+    *,
+    cleanup: bool,
+    managed_scopes: tuple[str, ...],
+) -> None:
+    active = [
+        SecureDestination(root / name, trusted_root, f"Cline {name}")
+        for root, files in outputs.items()
+        for name in files
+    ]
+    stale: list[SecureDestination] = []
+    if cleanup:
+        scopes = set(managed_scopes)
+        for root, files in outputs.items():
+            for path in _managed_paths(root, scopes):
+                if path.name not in files:
+                    stale.append(
+                        SecureDestination(path, trusted_root, f"Cline stale {path.name}")
+                    )
+
+    def apply(transaction: SecureTransaction) -> None:
+        for destination in active:
+            root_files = outputs[destination.path.parent]
+            transaction.atomic_write(
+                destination,
+                root_files[destination.path.name],
+                0o644,
+            )
+        for destination in stale:
+            transaction.unlink(destination)
+
+    run_secure_transaction(active + stale, apply)
+    for root, files in outputs.items():
+        for name in files:
+            print(f"  Generated: {(root / name).relative_to(target)}")
+
+
+def generate(
+    target_dir: Path,
+    *,
+    language_modules: list[str] | None = None,
+    rules_dir: Path | None = None,
+    cleanup: bool = True,
+    emit_workflows: bool = True,
+    managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,),
+    output_root: Path | None = None,
+) -> None:
     """Write Cline rule files.
 
-    By default writes project-local ``target_dir/.clinerules/*.md``. When
-    ``output_root`` is provided, writes directly into that directory; this is
-    used for Cline's documented global rules directory.
+    By default writes project-local ``target_dir/.cline/rules/*.md`` and the
+    extension-compatible ``target_dir/.clinerules/*.md``. When ``output_root``
+    is provided, writes only into that directory so installers can target one
+    documented global rules root at a time.
     """
-    # Migrate: if .clinerules exists as a single file, remove it so the
-    # directory can be created (Cline 3.7+ uses directory format).
-    if output_root is None:
-        clinerules = target_dir / ".clinerules"
-        if clinerules.is_file():
-            clinerules.unlink()
+    target, trusted_root = _trusted_target(target_dir)
+    legacy_clinerules = target / ".clinerules"
+    if legacy_clinerules.is_symlink():
+        raise RuntimeError(f"Unsafe symlinked Cline rules root: {legacy_clinerules}")
+    preserve_legacy_file = output_root is None and legacy_clinerules.is_file()
 
     rules: dict[str, callable] = dict(STANDARD_RULES)
     # Replace the testing rule with a conditional variant so it only
@@ -112,38 +207,110 @@ def generate(target_dir: Path, *,
             # "common" spans all languages — apply unconditionally.
             rules[filename] = content_fn
             continue
-        rules[filename] = (lambda fn, l: lambda: _wrap_language_rule(fn(), l))(
-            content_fn, lang,
-        )
+        rules[filename] = (
+            lambda fn, language: lambda: _wrap_language_rule(fn(), language)
+        )(content_fn, lang)
 
     rules.update(build_registered_rules(rules_dir))
 
-    root = output_root.parent if output_root is not None else target_dir
-    subdir = output_root.name if output_root is not None else ".clinerules"
-    write_rules(
-        root,
-        rules,
-        subdir,
+    rendered_rules = _render_rules(rules)
+    if output_root is None:
+        rule_roots = [target / ".cline" / "rules"]
+        if not preserve_legacy_file:
+            rule_roots.append(target / ".clinerules")
+    else:
+        rule_roots = [_output_root(target, output_root)]
+    outputs = {root: rendered_rules for root in rule_roots}
+    if emit_workflows and output_root is None and not preserve_legacy_file:
+        outputs[target / ".clinerules" / "workflows"] = _render_rules(
+            dict(STANDARD_WORKFLOWS)
+        )
+    _preflight_roots(target, list(outputs), trusted_root)
+    _write_transaction(
+        target,
+        trusted_root,
+        outputs,
         cleanup=cleanup,
         managed_scopes=managed_scopes,
     )
 
-    if emit_workflows and output_root is None:
-        _write_workflows(target_dir, cleanup=cleanup)
 
+def _managed_roots(
+    target: Path,
+    output_roots: tuple[Path, ...] | None,
+    include_workflows: bool,
+) -> list[Path]:
+    if output_roots is not None:
+        return [_output_root(target, root) for root in output_roots]
+    roots = [target / ".cline" / "rules"]
+    legacy = target / ".clinerules"
+    if legacy.is_symlink():
+        raise RuntimeError(f"Unsafe symlinked Cline rules root: {legacy}")
+    if not legacy.is_file():
+        roots.append(legacy)
+        if include_workflows:
+            roots.append(legacy / "workflows")
+    return roots
 
-def _write_workflows(target_dir: Path, *, cleanup: bool = True) -> None:
-    """Write ``.clinerules/workflows/*.md`` files (Cline slash-invocable)."""
-    workflows_dir = target_dir / ".clinerules" / "workflows"
-    workflows_dir.mkdir(parents=True, exist_ok=True)
 
-    if cleanup:
-        # Only touch ai-toolkit-* files; never remove user workflows.
-        cleanup_stale(workflows_dir, set(STANDARD_WORKFLOWS.keys()))
+def managed_files(
+    target_dir: Path,
+    *,
+    output_roots: tuple[Path, ...] | None = None,
+    include_workflows: bool = True,
+) -> list[Path]:
+    """List Cline rule artifacts owned by ai-toolkit."""
+    target, trusted_root = _trusted_target(target_dir)
+    roots = _managed_roots(target, output_roots, include_workflows)
+    _preflight_roots(target, roots, trusted_root)
+    paths = [
+        path
+        for root in roots
+        for path in _managed_paths(root, {STANDARD_SCOPE, "lang", "custom"})
+    ]
+    destinations = [
+        SecureDestination(path, trusted_root, f"Cline managed {path.name}")
+        for path in paths
+    ]
+    if not destinations:
+        return []
+    transaction = SecureTransaction(destinations)
+    try:
+        return [
+            destination.path
+            for destination in destinations
+            if transaction.initial_content(destination) is not None
+        ]
+    finally:
+        transaction.close()
+
+
+def cleanup(
+    target_dir: Path,
+    *,
+    output_roots: tuple[Path, ...] | None = None,
+    include_workflows: bool = True,
+) -> int:
+    """Remove only ai-toolkit-managed Cline rule and workflow files."""
+    files = managed_files(
+        target_dir,
+        output_roots=output_roots,
+        include_workflows=include_workflows,
+    )
+    if not files:
+        return 0
+    _, trusted_root = _trusted_target(target_dir)
+    destinations = [
+        SecureDestination(path, trusted_root, f"Cline managed {path.name}")
+        for path in files
+    ]
+
+    def apply(transaction: SecureTransaction) -> None:
+        for destination in destinations:
+            transaction.unlink(destination)
 
-    for filename, content_fn in STANDARD_WORKFLOWS.items():
-        (workflows_dir / filename).write_text(content_fn(), encoding="utf-8")
-        print(f"  Generated: .clinerules/workflows/{filename}")
+    run_secure_transaction(destinations, apply)
+    return len(files)
 
 
 def main() -> None: