deepwork 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

deepwork/core/command_executor.py

@@ -0,0 +1,173 @@
+"""Execute command actions for rules."""
+
+import shlex
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from deepwork.core.rules_parser import CommandAction
+
+
+@dataclass
+class CommandResult:
+    """Result of executing a command."""
+
+    success: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    command: str  # The actual command that was run
+
+
+def substitute_command_variables(
+    command_template: str,
+    file: str | None = None,
+    files: list[str] | None = None,
+    repo_root: Path | None = None,
+) -> str:
+    """
+    Substitute template variables in a command string.
+
+    Variables:
+    - {file} - Single file path
+    - {files} - Space-separated file paths
+    - {repo_root} - Repository root directory
+
+    Args:
+        command_template: Command string with {var} placeholders
+        file: Single file path (for run_for: each_match)
+        files: List of file paths (for run_for: all_matches)
+        repo_root: Repository root path
+
+    Returns:
+        Command string with variables substituted
+    """
+    result = command_template
+
+    if file is not None:
+        # Quote file path to prevent command injection
+        result = result.replace("{file}", shlex.quote(file))
+
+    if files is not None:
+        # Quote each file path individually
+        quoted_files = " ".join(shlex.quote(f) for f in files)
+        result = result.replace("{files}", quoted_files)
+
+    if repo_root is not None:
+        result = result.replace("{repo_root}", shlex.quote(str(repo_root)))
+
+    return result
+
+
+def execute_command(
+    command: str,
+    cwd: Path | None = None,
+    timeout: int = 60,
+) -> CommandResult:
+    """
+    Execute a command and capture output.
+
+    Args:
+        command: Command string to execute
+        cwd: Working directory (defaults to current directory)
+        timeout: Timeout in seconds
+
+    Returns:
+        CommandResult with execution details
+    """
+    try:
+        # Run command as shell to support pipes, etc.
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+
+        return CommandResult(
+            success=result.returncode == 0,
+            exit_code=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            command=command,
+        )
+
+    except subprocess.TimeoutExpired:
+        return CommandResult(
+            success=False,
+            exit_code=-1,
+            stdout="",
+            stderr=f"Command timed out after {timeout} seconds",
+            command=command,
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            exit_code=-1,
+            stdout="",
+            stderr=str(e),
+            command=command,
+        )
+
+
+def run_command_action(
+    action: CommandAction,
+    trigger_files: list[str],
+    repo_root: Path | None = None,
+) -> list[CommandResult]:
+    """
+    Run a command action for the given trigger files.
+
+    Args:
+        action: CommandAction configuration
+        trigger_files: Files that triggered the rule
+        repo_root: Repository root path
+
+    Returns:
+        List of CommandResult (one per command execution)
+    """
+    results: list[CommandResult] = []
+
+    if action.run_for == "each_match":
+        # Run command for each file individually
+        for file_path in trigger_files:
+            command = substitute_command_variables(
+                action.command,
+                file=file_path,
+                repo_root=repo_root,
+            )
+            result = execute_command(command, cwd=repo_root)
+            results.append(result)
+
+    elif action.run_for == "all_matches":
+        # Run command once with all files
+        command = substitute_command_variables(
+            action.command,
+            files=trigger_files,
+            repo_root=repo_root,
+        )
+        result = execute_command(command, cwd=repo_root)
+        results.append(result)
+
+    return results
+
+
+def all_commands_succeeded(results: list[CommandResult]) -> bool:
+    """Check if all command executions succeeded."""
+    return all(r.success for r in results)
+
+
+def format_command_errors(results: list[CommandResult]) -> str:
+    """Format error messages from failed commands."""
+    errors: list[str] = []
+    for result in results:
+        if not result.success:
+            msg = f"Command failed: {result.command}\n"
+            if result.stderr:
+                msg += f"Error: {result.stderr}\n"
+            if result.exit_code != 0:
+                msg += f"Exit code: {result.exit_code}\n"
+            errors.append(msg)
+    return "\n".join(errors)

deepwork/core/generator.py

@@ -1,24 +1,24 @@
-"""Slash-command file generator using Jinja2 templates."""
+"""Skill file generator using Jinja2 templates."""
 
 from pathlib import Path
 from typing import Any
 
 from jinja2 import Environment, FileSystemLoader, TemplateNotFound
 
-from deepwork.core.adapters import AgentAdapter, CommandLifecycleHook
+from deepwork.core.adapters import AgentAdapter, SkillLifecycleHook
 from deepwork.core.parser import JobDefinition, Step
 from deepwork.schemas.job_schema import LIFECYCLE_HOOK_EVENTS
 from deepwork.utils.fs import safe_read, safe_write
 
 
 class GeneratorError(Exception):
-    """Exception raised for command generation errors."""
+    """Exception raised for skill generation errors."""
 
     pass
 
 
-class CommandGenerator:
-    """Generates slash-command files from job definitions."""
+class SkillGenerator:
+    """Generates skill files from job definitions."""
 
     def __init__(self, templates_dir: Path | str | None = None):
         """
@@ -163,7 +163,7 @@ class CommandGenerator:
         for event in LIFECYCLE_HOOK_EVENTS:
             if event in step.hooks:
                 # Get platform-specific event name from adapter
-                hook_enum = CommandLifecycleHook(event)
+                hook_enum = SkillLifecycleHook(event)
                 platform_event_name = adapter.get_platform_hook_name(hook_enum)
                 if platform_event_name:
                     hook_contexts = [
@@ -175,7 +175,7 @@ class CommandGenerator:
 
         # Backward compatibility: stop_hooks is after_agent hooks
         stop_hooks = hooks.get(
-            adapter.get_platform_hook_name(CommandLifecycleHook.AFTER_AGENT) or "Stop", []
+            adapter.get_platform_hook_name(SkillLifecycleHook.AFTER_AGENT) or "Stop", []
         )
 
         return {
@@ -199,9 +199,117 @@ class CommandGenerator:
             "is_standalone": is_standalone,
             "hooks": hooks,  # New: all hooks by platform event name
             "stop_hooks": stop_hooks,  # Backward compat: after_agent hooks only
+            "quality_criteria": step.quality_criteria,  # Declarative criteria with framing
         }
 
-    def generate_step_command(
+    def _build_meta_skill_context(
+        self, job: JobDefinition, adapter: AgentAdapter
+    ) -> dict[str, Any]:
+        """
+        Build template context for a job's meta-skill.
+
+        Args:
+            job: Job definition
+            adapter: Agent adapter for platform-specific configuration
+
+        Returns:
+            Template context dictionary
+        """
+        # Build step info for the meta-skill
+        steps_info = []
+        for step in job.steps:
+            skill_filename = adapter.get_step_skill_filename(job.name, step.id, step.exposed)
+            # Extract just the skill name (without path and extension)
+            # For Claude: job_name.step_id/SKILL.md -> job_name.step_id
+            # For Gemini: job_name/step_id.toml -> job_name:step_id
+            if adapter.name == "gemini":
+                # Gemini uses colon for namespacing: job_name:step_id
+                parts = skill_filename.replace(".toml", "").split("/")
+                skill_name = ":".join(parts)
+            else:
+                # Claude uses directory/SKILL.md format, extract directory name
+                # job_name.step_id/SKILL.md -> job_name.step_id
+                skill_name = skill_filename.replace("/SKILL.md", "")
+
+            steps_info.append(
+                {
+                    "id": step.id,
+                    "name": step.name,
+                    "description": step.description,
+                    "command_name": skill_name,
+                    "dependencies": step.dependencies,
+                    "exposed": step.exposed,
+                }
+            )
+
+        return {
+            "job_name": job.name,
+            "job_version": job.version,
+            "job_summary": job.summary,
+            "job_description": job.description,
+            "total_steps": len(job.steps),
+            "steps": steps_info,
+        }
+
+    def generate_meta_skill(
+        self,
+        job: JobDefinition,
+        adapter: AgentAdapter,
+        output_dir: Path | str,
+    ) -> Path:
+        """
+        Generate the meta-skill file for a job.
+
+        The meta-skill is the primary user interface for a job, routing
+        user intent to the appropriate step.
+
+        Args:
+            job: Job definition
+            adapter: Agent adapter for the target platform
+            output_dir: Directory to write skill file to
+
+        Returns:
+            Path to generated meta-skill file
+
+        Raises:
+            GeneratorError: If generation fails
+        """
+        output_dir = Path(output_dir)
+
+        # Create skills subdirectory if needed
+        skills_dir = output_dir / adapter.skills_dir
+        skills_dir.mkdir(parents=True, exist_ok=True)
+
+        # Build context
+        context = self._build_meta_skill_context(job, adapter)
+
+        # Load and render template
+        env = self._get_jinja_env(adapter)
+        try:
+            template = env.get_template(adapter.meta_skill_template)
+        except TemplateNotFound as e:
+            raise GeneratorError(f"Meta-skill template not found: {e}") from e
+
+        try:
+            rendered = template.render(**context)
+        except Exception as e:
+            raise GeneratorError(f"Meta-skill template rendering failed: {e}") from e
+
+        # Write meta-skill file
+        skill_filename = adapter.get_meta_skill_filename(job.name)
+        skill_path = skills_dir / skill_filename
+
+        # Ensure parent directories exist (for Gemini's job_name/index.toml structure)
+        skill_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            safe_write(skill_path, rendered)
+        except Exception as e:
+            raise GeneratorError(f"Failed to write meta-skill file: {e}") from e
+
+        return skill_path
+
+    def generate_step_skill(
         self,
         job: JobDefinition,
         step: Step,
@@ -209,25 +317,25 @@ class CommandGenerator:
         output_dir: Path | str,
     ) -> Path:
         """
-        Generate slash-command file for a single step.
+        Generate skill file for a single step.
 
         Args:
             job: Job definition
-            step: Step to generate command for
+            step: Step to generate skill for
             adapter: Agent adapter for the target platform
-            output_dir: Directory to write command file to
+            output_dir: Directory to write skill file to
 
         Returns:
-            Path to generated command file
+            Path to generated skill file
 
         Raises:
             GeneratorError: If generation fails
         """
         output_dir = Path(output_dir)
 
-        # Create commands subdirectory if needed
-        commands_dir = output_dir / adapter.commands_dir
-        commands_dir.mkdir(parents=True, exist_ok=True)
+        # Create skills subdirectory if needed
+        skills_dir = output_dir / adapter.skills_dir
+        skills_dir.mkdir(parents=True, exist_ok=True)
 
         # Find step index
         try:
@@ -235,13 +343,14 @@ class CommandGenerator:
         except StopIteration as e:
             raise GeneratorError(f"Step '{step.id}' not found in job '{job.name}'") from e
 
-        # Build context
+        # Build context (include exposed for template user-invocable setting)
         context = self._build_step_context(job, step, step_index, adapter)
+        context["exposed"] = step.exposed
 
         # Load and render template
         env = self._get_jinja_env(adapter)
         try:
-            template = env.get_template(adapter.command_template)
+            template = env.get_template(adapter.skill_template)
         except TemplateNotFound as e:
             raise GeneratorError(f"Template not found: {e}") from e
 
@@ -250,41 +359,49 @@ class CommandGenerator:
         except Exception as e:
             raise GeneratorError(f"Template rendering failed: {e}") from e
 
-        # Write command file
-        command_filename = adapter.get_command_filename(job.name, step.id)
-        command_path = commands_dir / command_filename
+        # Write skill file
+        skill_filename = adapter.get_step_skill_filename(job.name, step.id, step.exposed)
+        skill_path = skills_dir / skill_filename
+
+        # Ensure parent directories exist (for Gemini's job_name/step_id.toml structure)
+        skill_path.parent.mkdir(parents=True, exist_ok=True)
 
         try:
-            safe_write(command_path, rendered)
+            safe_write(skill_path, rendered)
         except Exception as e:
-            raise GeneratorError(f"Failed to write command file: {e}") from e
+            raise GeneratorError(f"Failed to write skill file: {e}") from e
 
-        return command_path
+        return skill_path
 
-    def generate_all_commands(
+    def generate_all_skills(
         self,
         job: JobDefinition,
         adapter: AgentAdapter,
         output_dir: Path | str,
     ) -> list[Path]:
         """
-        Generate slash-command files for all steps in a job.
+        Generate all skill files for a job: meta-skill and step skills.
 
         Args:
             job: Job definition
             adapter: Agent adapter for the target platform
-            output_dir: Directory to write command files to
+            output_dir: Directory to write skill files to
 
         Returns:
-            List of paths to generated command files
+            List of paths to generated skill files (meta-skill first, then steps)
 
         Raises:
             GeneratorError: If generation fails
         """
-        command_paths = []
+        skill_paths = []
+
+        # Generate meta-skill first (job-level entry point)
+        meta_skill_path = self.generate_meta_skill(job, adapter, output_dir)
+        skill_paths.append(meta_skill_path)
 
+        # Generate step skills
         for step in job.steps:
-            command_path = self.generate_step_command(job, step, adapter, output_dir)
-            command_paths.append(command_path)
+            skill_path = self.generate_step_skill(job, step, adapter, output_dir)
+            skill_paths.append(skill_path)
 
-        return command_paths
+        return skill_paths

deepwork/core/hooks_syncer.py

@@ -19,27 +19,42 @@ class HooksSyncError(Exception):
 class HookEntry:
     """Represents a single hook entry for a lifecycle event."""
 
-    script: str  # Script filename
     job_name: str  # Job that provides this hook
     job_dir: Path  # Full path to job directory
+    script: str | None = None  # Script filename (if script-based hook)
+    module: str | None = None  # Python module (if module-based hook)
 
-    def get_script_path(self, project_path: Path) -> str:
+    def get_command(self, project_path: Path) -> str:
         """
-        Get the script path relative to project root.
+        Get the command to run this hook.
 
         Args:
             project_path: Path to project root
 
         Returns:
-            Relative path to script from project root
+            Command string to execute
         """
-        # Script path is: .deepwork/jobs/{job_name}/hooks/{script}
-        script_path = self.job_dir / "hooks" / self.script
-        try:
-            return str(script_path.relative_to(project_path))
-        except ValueError:
-            # If not relative, return the full path
-            return str(script_path)
+        if self.module:
+            # Python module - run directly with python -m
+            return f"python -m {self.module}"
+        elif self.script:
+            # Script path is: .deepwork/jobs/{job_name}/hooks/{script}
+            script_path = self.job_dir / "hooks" / self.script
+            try:
+                return str(script_path.relative_to(project_path))
+            except ValueError:
+                # If not relative, return the full path
+                return str(script_path)
+        else:
+            raise ValueError("HookEntry must have either script or module")
+
+
+@dataclass
+class HookSpec:
+    """Specification for a single hook (either script or module)."""
+
+    script: str | None = None
+    module: str | None = None
 
 
 @dataclass
@@ -48,7 +63,7 @@ class JobHooks:
 
     job_name: str
     job_dir: Path
-    hooks: dict[str, list[str]] = field(default_factory=dict)  # event -> [scripts]
+    hooks: dict[str, list[HookSpec]] = field(default_factory=dict)  # event -> [HookSpec]
 
     @classmethod
     def from_job_dir(cls, job_dir: Path) -> "JobHooks | None":
@@ -74,13 +89,23 @@ class JobHooks:
         if not data or not isinstance(data, dict):
             return None
 
-        # Parse hooks - each key is an event, value is list of scripts
-        hooks: dict[str, list[str]] = {}
-        for event, scripts in data.items():
-            if isinstance(scripts, list):
-                hooks[event] = [str(s) for s in scripts]
-            elif isinstance(scripts, str):
-                hooks[event] = [scripts]
+        # Parse hooks - each key is an event, value is list of scripts or module specs
+        hooks: dict[str, list[HookSpec]] = {}
+        for event, entries in data.items():
+            if not isinstance(entries, list):
+                entries = [entries]
+
+            hook_specs: list[HookSpec] = []
+            for entry in entries:
+                if isinstance(entry, str):
+                    # Simple script filename
+                    hook_specs.append(HookSpec(script=entry))
+                elif isinstance(entry, dict) and "module" in entry:
+                    # Python module specification
+                    hook_specs.append(HookSpec(module=entry["module"]))
+
+            if hook_specs:
+                hooks[event] = hook_specs
 
         if not hooks:
             return None
@@ -134,17 +159,18 @@ def merge_hooks_for_platform(
     merged: dict[str, list[dict[str, Any]]] = {}
 
     for job_hooks in job_hooks_list:
-        for event, scripts in job_hooks.hooks.items():
+        for event, hook_specs in job_hooks.hooks.items():
             if event not in merged:
                 merged[event] = []
 
-            for script in scripts:
+            for spec in hook_specs:
                 entry = HookEntry(
-                    script=script,
                     job_name=job_hooks.job_name,
                     job_dir=job_hooks.job_dir,
+                    script=spec.script,
+                    module=spec.module,
                 )
-                script_path = entry.get_script_path(project_path)
+                command = entry.get_command(project_path)
 
                 # Create hook configuration for Claude Code format
                 hook_config = {
@@ -152,13 +178,13 @@ def merge_hooks_for_platform(
                     "hooks": [
                         {
                             "type": "command",
-                            "command": script_path,
+                            "command": command,
                         }
                     ],
                 }
 
                 # Check if this hook is already present (avoid duplicates)
-                if not _hook_already_present(merged[event], script_path):
+                if not _hook_already_present(merged[event], command):
                     merged[event].append(hook_config)
 
     return merged

deepwork/core/parser.py

@@ -108,6 +108,12 @@ class Step:
     # Event names: after_agent, before_tool, before_prompt
     hooks: dict[str, list[HookAction]] = field(default_factory=dict)
 
+    # If true, skill is user-invocable in menus. Default: false (hidden from menus).
+    exposed: bool = False
+
+    # Declarative quality criteria rendered with standard evaluation framing
+    quality_criteria: list[str] = field(default_factory=list)
+
     @property
     def stop_hooks(self) -> list[HookAction]:
         """
@@ -144,6 +150,8 @@ class Step:
             outputs=data["outputs"],
             dependencies=data.get("dependencies", []),
             hooks=hooks,
+            exposed=data.get("exposed", False),
+            quality_criteria=data.get("quality_criteria", []),
         )