@softspark/ai-toolkit 2.12.0 → 3.0.0

package/scripts/generate_cline_rules.py

@@ -1,9 +1,18 @@
 #!/usr/bin/env python3
-"""Generate .clinerules/*.md files for Cline.
+"""Generate ``.clinerules/*.md`` files and companion workflows for Cline.
 
-Cline reads rules from the .clinerules/ directory (since Cline 3.7).
-Each .md file inside .clinerules/ is automatically loaded.
-The legacy .clinerules single-file format is replaced by this directory.
+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.
+
+This generator also produces:
+  * ``.clinerules/workflows/*.md`` — project-local workflow files that
+    users invoke with ``/name.md`` in Cline chat. Emitted by default and
+    mirrors the same workflow catalogue used by Antigravity and Codex.
+  * Conditional rules (YAML ``paths:`` frontmatter) for file-type-scoped
+    rules such as testing and language-specific guidance, so Cline only
+    loads them when the user is editing matching files. See Cline docs:
+    customization/cline-rules#conditional-rules.
 
 Usage:
   python3 scripts/generate_cline_rules.py [target-dir]
@@ -15,28 +24,89 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from dir_rules_shared import (
+    LANG_GLOBS,
+    LANG_PREFIX,
+    PREFIX,
     STANDARD_RULES,
     STANDARD_SCOPE,
+    STANDARD_WORKFLOWS,
     build_language_rules,
     build_registered_rules,
+    cleanup_stale,
+    rule_testing,
     write_rules,
 )
 
 
+# ---------------------------------------------------------------------------
+# Conditional-rule helper
+# ---------------------------------------------------------------------------
+
+def _conditional(content: str, paths: list[str]) -> str:
+    """Prepend a Cline ``paths:`` YAML frontmatter block.
+
+    Cline activates the rule only when the current working files match
+    one of the globs. See docs.cline.bot → customization/cline-rules.
+    """
+    lines = ["---", "paths:"]
+    for p in paths:
+        lines.append(f'  - "{p}"')
+    lines.append("---")
+    lines.append("")
+    lines.append(content.rstrip("\n"))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _conditional_testing_rule() -> str:
+    """Scope the testing rule to test files only (reduces context use)."""
+    return _conditional(
+        rule_testing(),
+        ["**/*.test.*", "**/*.spec.*", "**/test_*", "**/tests/**"],
+    )
+
+
+def _wrap_language_rule(raw: str, lang: str) -> str:
+    """Scope a language rule to its file extensions via conditional ``paths``."""
+    globs = LANG_GLOBS.get(lang)
+    if not globs:
+        return raw
+    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,)) -> None:
-    """Write .clinerules/*.md files to target_dir."""
-    # Migrate: if .clinerules exists as a single file, remove it
-    # so the directory can be created (Cline 3.7+ uses directory format)
+    """Write ``.clinerules/*.md`` (and workflow) files to target_dir."""
+    # Migrate: if .clinerules exists as a single file, remove it so the
+    # directory can be created (Cline 3.7+ uses directory format).
     clinerules = target_dir / ".clinerules"
     if clinerules.is_file():
         clinerules.unlink()
-    rules = dict(STANDARD_RULES)
-    rules.update(build_language_rules(language_modules))
+
+    rules: dict[str, callable] = dict(STANDARD_RULES)
+    # Replace the testing rule with a conditional variant so it only
+    # loads when the user is editing tests.
+    rules[f"{PREFIX}testing.md"] = _conditional_testing_rule
+
+    # Language rules — wrap each in conditional frontmatter scoped to
+    # the language's file globs so the language-specific guidance only
+    # loads for matching files.
+    for filename, content_fn in build_language_rules(language_modules).items():
+        lang = filename.removeprefix(LANG_PREFIX).removesuffix(".md")
+        if lang == "common":
+            # "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.update(build_registered_rules(rules_dir))
+
     write_rules(
         target_dir,
         rules,
@@ -45,6 +115,23 @@ def generate(target_dir: Path, *,
         managed_scopes=managed_scopes,
     )
 
+    if emit_workflows:
+        _write_workflows(target_dir, cleanup=cleanup)
+
+
+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()))
+
+    for filename, content_fn in STANDARD_WORKFLOWS.items():
+        (workflows_dir / filename).write_text(content_fn(), encoding="utf-8")
+        print(f"  Generated: .clinerules/workflows/{filename}")
+
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()

package/scripts/generate_codex_hooks.py

@@ -4,8 +4,13 @@
 Maps compatible ai-toolkit hooks to Codex lifecycle events.
 Hook scripts are shared with Claude Code (stored in ~/.softspark/ai-toolkit/hooks/).
 
-Codex supports 5 events: SessionStart, PreToolUse, PostToolUse,
-UserPromptSubmit, Stop. PreToolUse/PostToolUse only support Bash matcher.
+Codex supports 6 events (PascalCase in config.toml / hooks.json):
+``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``SessionStart``,
+``UserPromptSubmit``, ``Stop``. PreToolUse/PostToolUse only support
+the ``Bash`` matcher.
+
+Handler types in Codex: ``command`` (what we emit), ``prompt``, and ``agent``.
+Reference: codex-rs/config/src/hook_config.rs.
 
 Usage:
   python3 scripts/generate_codex_hooks.py [target-dir]
@@ -33,6 +38,12 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("Bash", "guard-destructive.sh"),
         ("Bash", "commit-quality.sh"),
     ],
+    "PermissionRequest": [
+        # Fires when Codex asks the user to approve a tool call. Our guard
+        # reviews the tool input and can veto destructive patterns before the
+        # approval prompt reaches the human.
+        ("", "guard-destructive.sh"),
+    ],
     "UserPromptSubmit": [
         ("", "user-prompt-submit.sh"),
         ("", "track-usage.sh"),

package/scripts/generate_codex_skills.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Mirror the full ai-toolkit skill catalogue into ``.codex/skills/``.
+
+OpenAI Codex CLI supports the Agent Skills standard at
+``.codex/skills/<skill-name>/SKILL.md`` with optional supporting files
+(scripts, references, assets) in the skill directory. Unlike the Augment
+and Gemini pointer pattern, Codex benefits from having the full skill
+content on disk, so this generator performs a **full mirror** of every
+skill in ``app/skills/`` into ``<target-dir>/.codex/skills/<name>/``.
+
+The mirror is **opt-in**: ``enable_codex_skills=False`` is the default.
+Bucket 4 wires a ``--codex-skills`` CLI flag that toggles this on.
+
+Implementation:
+  * Prefer symlinks from ``.codex/skills/<name>`` to the canonical
+    ``app/skills/<name>`` directory (atomic and cheap).
+  * Fall back to a recursive copy when symlinks are unavailable (Windows
+    without developer mode, hostile filesystems, etc.).
+  * Skip ``_lib`` and any dotfile directories under ``app/skills/``.
+  * Remove stale entries under ``.codex/skills/`` that no longer
+    correspond to a source skill (cleanup on rerun).
+  * Never touch user-authored entries in ``.codex/skills/`` that do not
+    match a source skill name and are not our managed targets.
+
+Idempotent on rerun.
+
+Usage:
+  python3 scripts/generate_codex_skills.py [target-dir]
+
+By default the CLI entrypoint also requires ``--enable`` to write anything,
+keeping the opt-in default enforced even when invoked directly.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import skills_dir
+
+
+# ---------------------------------------------------------------------------
+# Source skill discovery
+# ---------------------------------------------------------------------------
+
+def _iter_source_skills() -> list[Path]:
+    """Return sorted list of source skill directories in ``app/skills/``.
+
+    Skills starting with ``_`` (library internals) or ``.`` are skipped.
+    Only directories containing a top-level ``SKILL.md`` are returned.
+    """
+    if not skills_dir.is_dir():
+        return []
+    entries: list[Path] = []
+    for entry in sorted(skills_dir.iterdir()):
+        if not entry.is_dir():
+            continue
+        if entry.name.startswith("_") or entry.name.startswith("."):
+            continue
+        if not (entry / "SKILL.md").is_file():
+            continue
+        entries.append(entry)
+    return entries
+
+
+# ---------------------------------------------------------------------------
+# Mirror operations
+# ---------------------------------------------------------------------------
+
+def _remove_existing(target: Path) -> None:
+    """Remove an existing file, symlink, or directory at ``target``.
+
+    Uses ``lstat`` so symlinks are unlinked without following them.
+    """
+    if not target.exists() and not target.is_symlink():
+        return
+    if target.is_symlink() or target.is_file():
+        target.unlink()
+        return
+    shutil.rmtree(target)
+
+
+def _symlink_or_copy(source: Path, target: Path) -> str:
+    """Create ``target`` as a symlink to ``source``; fall back to a copy.
+
+    Returns ``"symlink"`` or ``"copy"`` indicating which strategy was used.
+    """
+    _remove_existing(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.symlink(source, target, target_is_directory=True)
+        return "symlink"
+    except (OSError, NotImplementedError):
+        shutil.copytree(source, target, symlinks=False)
+        return "copy"
+
+
+def _cleanup_stale(codex_skills_dir: Path, live_names: set[str]) -> list[str]:
+    """Remove managed entries under ``.codex/skills/`` that no longer map
+    to a source skill. Returns the names removed.
+
+    A managed entry is one whose directory name matches a historical
+    source skill name pattern: it contains a ``SKILL.md`` either directly
+    (copy) or via a symlink back into ``app/skills/``. User-authored
+    entries that do not look managed are left alone.
+    """
+    if not codex_skills_dir.is_dir():
+        return []
+    removed: list[str] = []
+    for entry in sorted(codex_skills_dir.iterdir()):
+        if not entry.is_dir() and not entry.is_symlink():
+            continue
+        if entry.name in live_names:
+            continue
+        if entry.is_symlink():
+            # Only remove symlinks that point inside our app/skills/ tree.
+            try:
+                resolved = entry.resolve()
+            except OSError:
+                continue
+            try:
+                resolved.relative_to(skills_dir.resolve())
+            except ValueError:
+                continue
+            entry.unlink()
+            removed.append(entry.name)
+            continue
+        # Copy mode: treat as managed only if a SKILL.md is present.
+        if (entry / "SKILL.md").is_file():
+            shutil.rmtree(entry)
+            removed.append(entry.name)
+    return removed
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def generate(target_dir: Path, enable_codex_skills: bool = False) -> None:
+    """Mirror ``app/skills/`` into ``<target_dir>/.codex/skills/``.
+
+    Args:
+      target_dir: Project root where ``.codex/skills/`` is written.
+      enable_codex_skills: Opt-in flag. Defaults to ``False`` (no-op).
+
+    Contract for Bucket 4 wiring::
+
+        from scripts.generate_codex_skills import generate as gen_codex_skills
+        gen_codex_skills(target_dir, enable_codex_skills=cli_flag)
+
+    The ``--codex-skills`` CLI flag should propagate straight into
+    ``enable_codex_skills``.
+    """
+    if not enable_codex_skills:
+        return
+
+    codex_skills_dir = target_dir / ".codex" / "skills"
+    codex_skills_dir.mkdir(parents=True, exist_ok=True)
+
+    sources = _iter_source_skills()
+    live_names: set[str] = {s.name for s in sources}
+
+    symlink_count = 0
+    copy_count = 0
+    for skill in sources:
+        target = codex_skills_dir / skill.name
+        mode = _symlink_or_copy(skill, target)
+        if mode == "symlink":
+            symlink_count += 1
+        else:
+            copy_count += 1
+
+    removed = _cleanup_stale(codex_skills_dir, live_names)
+
+    total = symlink_count + copy_count
+    print(
+        f"  Codex skill mirror: {total} skills "
+        f"({symlink_count} symlink, {copy_count} copy)"
+    )
+    if removed:
+        print(f"  Codex skill mirror: removed {len(removed)} stale entries")
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    enable = "--enable" in args
+    positional = [a for a in args if not a.startswith("--")]
+    target = Path(positional[0]) if positional else Path.cwd()
+    generate(target, enable_codex_skills=enable)
+
+
+if __name__ == "__main__":
+    main()