deepwork 0.3.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

deepwork/cli/hook.py

@@ -0,0 +1,70 @@
+"""Hook command for DeepWork CLI.
+
+This command runs hook scripts, allowing hooks to use the `deepwork` CLI
+instead of `python -m deepwork.hooks.*`, which works regardless of how
+deepwork was installed (flake, pipx, uv, etc.).
+
+Usage:
+    deepwork hook rules_check
+    deepwork hook <hook_name>
+
+This is meant to be called from hook wrapper scripts (claude_hook.sh, gemini_hook.sh).
+"""
+
+import importlib
+import sys
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+class HookError(Exception):
+    """Exception raised for hook errors."""
+
+    pass
+
+
+@click.command()
+@click.argument("hook_name")
+def hook(hook_name: str) -> None:
+    """
+    Run a DeepWork hook by name.
+
+    HOOK_NAME: Name of the hook to run (e.g., 'rules_check')
+
+    This command imports and runs the hook module from deepwork.hooks.{hook_name}.
+    The hook receives stdin input and outputs to stdout, following the hook protocol.
+
+    Examples:
+        deepwork hook rules_check
+        echo '{}' | deepwork hook rules_check
+    """
+    try:
+        # Import the hook module
+        # If the hook_name contains a dot, treat it as a full module path
+        # Otherwise, assume it's a hook in the deepwork.hooks package
+        if "." in hook_name:
+            module_name = hook_name
+        else:
+            module_name = f"deepwork.hooks.{hook_name}"
+        try:
+            module = importlib.import_module(module_name)
+        except ModuleNotFoundError:
+            raise HookError(
+                f"Hook '{hook_name}' not found. Available hooks are in the deepwork.hooks package."
+            ) from None
+
+        # Run the hook's main function if it exists
+        if hasattr(module, "main"):
+            sys.exit(module.main())
+        else:
+            raise HookError(f"Hook module '{module_name}' does not have a main() function")
+
+    except HookError as e:
+        console.print(f"[red]Error:[/red] {e}", style="bold red")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error running hook:[/red] {e}", style="bold red")
+        sys.exit(1)

deepwork/cli/install.py

@@ -8,7 +8,7 @@ from rich.console import Console
 
 from deepwork.core.adapters import AgentAdapter
 from deepwork.core.detector import PlatformDetector
-from deepwork.utils.fs import ensure_dir
+from deepwork.utils.fs import ensure_dir, fix_permissions
 from deepwork.utils.git import is_git_repo
 from deepwork.utils.yaml_utils import load_yaml, save_yaml
 
@@ -52,9 +52,24 @@ def _inject_standard_job(job_name: str, jobs_dir: Path, project_path: Path) -> N
             shutil.rmtree(target_dir)
 
         shutil.copytree(standard_jobs_dir, target_dir)
+        # Fix permissions - source may have restrictive permissions (e.g., read-only)
+        fix_permissions(target_dir)
         console.print(
             f"  [green]✓[/green] Installed {job_name} ({target_dir.relative_to(project_path)})"
         )
+
+        # Copy any doc specs from the standard job to .deepwork/doc_specs/
+        doc_specs_source = standard_jobs_dir / "doc_specs"
+        doc_specs_target = project_path / ".deepwork" / "doc_specs"
+        if doc_specs_source.exists():
+            for doc_spec_file in doc_specs_source.glob("*.md"):
+                target_doc_spec = doc_specs_target / doc_spec_file.name
+                shutil.copy(doc_spec_file, target_doc_spec)
+                # Fix permissions for copied doc spec
+                fix_permissions(target_doc_spec)
+                console.print(
+                    f"  [green]✓[/green] Installed doc spec {doc_spec_file.name} ({target_doc_spec.relative_to(project_path)})"
+                )
     except Exception as e:
         raise InstallError(f"Failed to install {job_name}: {e}") from e
 
@@ -91,26 +106,47 @@ def _create_deepwork_gitignore(deepwork_dir: Path) -> None:
     """
     Create .gitignore file in .deepwork/ directory.
 
-    This ensures that temporary files like .last_work_tree are not committed.
+    This ensures that runtime artifacts are not committed while keeping
+    the tmp directory structure in version control.
 
     Args:
         deepwork_dir: Path to .deepwork directory
     """
     gitignore_path = deepwork_dir / ".gitignore"
-    gitignore_content = """# DeepWork temporary files
-# These files are used for rules evaluation during sessions
+    gitignore_content = """# DeepWork runtime artifacts
+# These files are generated during sessions and should not be committed
 .last_work_tree
+.last_head_ref
+
+# Temporary files (but keep the directory via .gitkeep)
+tmp/*
+!tmp/.gitkeep
 """
 
-    # Only write if it doesn't exist or doesn't contain the entry
-    if gitignore_path.exists():
-        existing_content = gitignore_path.read_text()
-        if ".last_work_tree" not in existing_content:
-            # Append to existing
-            with open(gitignore_path, "a") as f:
-                f.write("\n" + gitignore_content)
-    else:
-        gitignore_path.write_text(gitignore_content)
+    # Always overwrite to ensure correct content
+    gitignore_path.write_text(gitignore_content)
+
+
+def _create_tmp_directory(deepwork_dir: Path) -> None:
+    """
+    Create the .deepwork/tmp directory with a .gitkeep file.
+
+    This ensures the tmp directory exists in version control, which is required
+    for file permissions to work correctly when Claude Code starts fresh.
+
+    Args:
+        deepwork_dir: Path to .deepwork directory
+    """
+    tmp_dir = deepwork_dir / "tmp"
+    ensure_dir(tmp_dir)
+
+    gitkeep_file = tmp_dir / ".gitkeep"
+    if not gitkeep_file.exists():
+        gitkeep_file.write_text(
+            "# This file ensures the .deepwork/tmp directory exists in version control.\n"
+            "# The tmp directory is used for temporary files during DeepWork operations.\n"
+            "# Do not delete this file.\n"
+        )
 
 
 def _create_rules_directory(project_path: Path) -> bool:
@@ -142,6 +178,8 @@ def _create_rules_directory(project_path: Path) -> bool:
         for example_file in example_rules_dir.glob("*.md.example"):
             dest_file = rules_dir / example_file.name
             shutil.copy(example_file, dest_file)
+            # Fix permissions for copied rule template
+            fix_permissions(dest_file)
 
     # Create a README file explaining the rules system
     readme_content = """# DeepWork Rules
@@ -307,8 +345,10 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
     console.print("[yellow]→[/yellow] Creating DeepWork directory structure...")
     deepwork_dir = project_path / ".deepwork"
     jobs_dir = deepwork_dir / "jobs"
+    doc_specs_dir = deepwork_dir / "doc_specs"
     ensure_dir(deepwork_dir)
     ensure_dir(jobs_dir)
+    ensure_dir(doc_specs_dir)
     console.print(f"  [green]✓[/green] Created {deepwork_dir.relative_to(project_path)}/")
 
     # Step 3b: Inject standard jobs (core job definitions)
@@ -320,7 +360,11 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
     _create_deepwork_gitignore(deepwork_dir)
     console.print("  [green]✓[/green] Created .deepwork/.gitignore")
 
-    # Step 3d: Create rules directory with v2 templates
+    # Step 3d: Create tmp directory with .gitkeep file for version control
+    _create_tmp_directory(deepwork_dir)
+    console.print("  [green]✓[/green] Created .deepwork/tmp/.gitkeep")
+
+    # Step 3e: Create rules directory with v2 templates
     if _create_rules_directory(project_path):
         console.print("  [green]✓[/green] Created .deepwork/rules/ with example templates")
     else:

deepwork/cli/main.py

@@ -14,11 +14,15 @@ def cli() -> None:
 
 
 # Import commands
+from deepwork.cli.hook import hook  # noqa: E402
 from deepwork.cli.install import install  # noqa: E402
+from deepwork.cli.rules import rules  # noqa: E402
 from deepwork.cli.sync import sync  # noqa: E402
 
 cli.add_command(install)
 cli.add_command(sync)
+cli.add_command(hook)
+cli.add_command(rules)
 
 
 if __name__ == "__main__":

deepwork/cli/rules.py

@@ -0,0 +1,32 @@
+"""Rules command for DeepWork CLI."""
+
+import click
+from rich.console import Console
+
+from deepwork.core.rules_queue import RulesQueue
+
+console = Console()
+
+
+@click.group()
+def rules() -> None:
+    """Manage DeepWork rules and queue."""
+    pass
+
+
+@rules.command(name="clear_queue")
+def clear_queue() -> None:
+    """
+    Clear all entries from the rules queue.
+
+    Removes all JSON files from .deepwork/tmp/rules/queue/.
+    This is useful for resetting the queue between tests or after
+    manual verification of rule states.
+    """
+    queue = RulesQueue()
+    count = queue.clear()
+
+    if count == 0:
+        console.print("[yellow]Queue is already empty[/yellow]")
+    else:
+        console.print(f"[green]Cleared {count} queue entry/entries[/green]")

deepwork/cli/sync.py

@@ -136,11 +136,15 @@ def sync_skills(project_path: Path) -> None:
         ensure_dir(skills_dir)
 
         # Generate skills for all jobs
+        all_skill_paths: list[Path] = []
         if jobs:
             console.print("  [dim]•[/dim] Generating skills...")
             for job in jobs:
                 try:
-                    job_paths = generator.generate_all_skills(job, adapter, platform_dir)
+                    job_paths = generator.generate_all_skills(
+                        job, adapter, platform_dir, project_root=project_path
+                    )
+                    all_skill_paths.extend(job_paths)
                     stats["skills"] += len(job_paths)
                     console.print(f"    [green]✓[/green] {job.name} ({len(job_paths)} skills)")
                 except Exception as e:
@@ -157,6 +161,28 @@ def sync_skills(project_path: Path) -> None:
             except Exception as e:
                 console.print(f"    [red]✗[/red] Failed to sync hooks: {e}")
 
+        # Sync required permissions to platform settings
+        console.print("  [dim]•[/dim] Syncing permissions...")
+        try:
+            perms_count = adapter.sync_permissions(project_path)
+            if perms_count > 0:
+                console.print(f"    [green]✓[/green] Added {perms_count} base permission(s)")
+            else:
+                console.print("    [dim]•[/dim] Base permissions already configured")
+        except Exception as e:
+            console.print(f"    [red]✗[/red] Failed to sync permissions: {e}")
+
+        # Add skill permissions for generated skills (if adapter supports it)
+        if all_skill_paths and hasattr(adapter, "add_skill_permissions"):
+            try:
+                skill_perms_count = adapter.add_skill_permissions(project_path, all_skill_paths)
+                if skill_perms_count > 0:
+                    console.print(
+                        f"    [green]✓[/green] Added {skill_perms_count} skill permission(s)"
+                    )
+            except Exception as e:
+                console.print(f"    [red]✗[/red] Failed to sync skill permissions: {e}")
+
         stats["platforms"] += 1
         synced_adapters.append(adapter)
 

deepwork/core/adapters.py

@@ -241,6 +241,25 @@ class AgentAdapter(ABC):
         """
         pass
 
+    def sync_permissions(self, project_path: Path) -> int:
+        """
+        Sync required permissions to platform settings.
+
+        This method adds any permissions that DeepWork requires to function
+        properly (e.g., access to .deepwork/tmp/ directory).
+
+        Args:
+            project_path: Path to project root
+
+        Returns:
+            Number of permissions added
+
+        Raises:
+            AdapterError: If sync fails
+        """
+        # Default implementation does nothing - subclasses can override
+        return 0
+
 
 def _hook_already_present(hooks: list[dict[str, Any]], script_path: str) -> bool:
     """Check if a hook with the given script path is already in the list."""
@@ -344,6 +363,200 @@ class ClaudeAdapter(AgentAdapter):
         total = sum(len(hooks_list) for hooks_list in hooks.values())
         return total
 
+    def _load_settings(self, project_path: Path) -> dict[str, Any]:
+        """
+        Load settings.json from the project.
+
+        Args:
+            project_path: Path to project root
+
+        Returns:
+            Settings dictionary (empty dict if file doesn't exist)
+
+        Raises:
+            AdapterError: If file exists but cannot be read
+        """
+        settings_file = project_path / self.config_dir / "settings.json"
+        if settings_file.exists():
+            try:
+                with open(settings_file, encoding="utf-8") as f:
+                    result: dict[str, Any] = json.load(f)
+                    return result
+            except (json.JSONDecodeError, OSError) as e:
+                raise AdapterError(f"Failed to read settings.json: {e}") from e
+        return {}
+
+    def _save_settings(self, project_path: Path, settings: dict[str, Any]) -> None:
+        """
+        Save settings.json to the project.
+
+        Args:
+            project_path: Path to project root
+            settings: Settings dictionary to save
+
+        Raises:
+            AdapterError: If file cannot be written
+        """
+        settings_file = project_path / self.config_dir / "settings.json"
+        try:
+            settings_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(settings_file, "w", encoding="utf-8") as f:
+                json.dump(settings, f, indent=2)
+        except OSError as e:
+            raise AdapterError(f"Failed to write settings.json: {e}") from e
+
+    def add_permission(
+        self, project_path: Path, permission: str, settings: dict[str, Any] | None = None
+    ) -> bool:
+        """
+        Add a single permission to settings.json allow list.
+
+        Args:
+            project_path: Path to project root
+            permission: The permission string to add (e.g., "Read(./.deepwork/tmp/**)")
+            settings: Optional pre-loaded settings dict. If provided, modifies in-place
+                     and does NOT save to disk (caller is responsible for saving).
+                     If None, loads settings, adds permission, and saves.
+
+        Returns:
+            True if permission was added, False if already present
+
+        Raises:
+            AdapterError: If settings cannot be read/written
+        """
+        save_after = settings is None
+        if settings is None:
+            settings = self._load_settings(project_path)
+
+        # Ensure permissions structure exists
+        if "permissions" not in settings:
+            settings["permissions"] = {}
+        if "allow" not in settings["permissions"]:
+            settings["permissions"]["allow"] = []
+
+        # Add permission if not already present
+        allow_list = settings["permissions"]["allow"]
+        if permission not in allow_list:
+            allow_list.append(permission)
+            if save_after:
+                self._save_settings(project_path, settings)
+            return True
+        return False
+
+    def sync_permissions(self, project_path: Path) -> int:
+        """
+        Sync required permissions to Claude Code settings.json.
+
+        Adds permissions for:
+        - .deepwork/** - full access to deepwork directory
+        - All deepwork CLI commands (deepwork:*)
+
+        Args:
+            project_path: Path to project root
+
+        Returns:
+            Number of permissions added
+
+        Raises:
+            AdapterError: If sync fails
+        """
+        # Define required permissions for DeepWork functionality
+        # Uses ./ prefix for paths relative to project root (per Claude Code docs)
+        required_permissions = [
+            # Full access to .deepwork directory
+            "Read(./.deepwork/**)",
+            "Edit(./.deepwork/**)",
+            "Write(./.deepwork/**)",
+            # All deepwork CLI commands
+            "Bash(deepwork:*)",
+            # Job scripts that need to be executable
+            "Bash(./.deepwork/jobs/deepwork_jobs/make_new_job.sh:*)",
+        ]
+        # NOTE: When modifying required_permissions, update the test assertion in
+        # tests/unit/test_adapters.py::TestClaudeAdapter::test_sync_permissions_idempotent
+
+        # Load settings once, add all permissions, then save once
+        settings = self._load_settings(project_path)
+        added_count = 0
+
+        for permission in required_permissions:
+            if self.add_permission(project_path, permission, settings):
+                added_count += 1
+
+        # Save if any permissions were added
+        if added_count > 0:
+            self._save_settings(project_path, settings)
+
+        return added_count
+
+    def add_skill_permissions(self, project_path: Path, skill_paths: list[Path]) -> int:
+        """
+        Add Skill permissions for generated skills to settings.json.
+
+        This allows Claude to invoke the skills without permission prompts.
+        Uses the Skill(name) permission syntax.
+
+        Note: Skill permissions are an emerging Claude Code feature and
+        behavior may vary between versions.
+
+        Args:
+            project_path: Path to project root
+            skill_paths: List of paths to generated skill files
+
+        Returns:
+            Number of permissions added
+
+        Raises:
+            AdapterError: If sync fails
+        """
+        if not skill_paths:
+            return 0
+
+        # Load settings once
+        settings = self._load_settings(project_path)
+        added_count = 0
+
+        for skill_path in skill_paths:
+            # Extract skill name from path
+            # Path format: .claude/skills/job_name/SKILL.md -> job_name
+            # Path format: .claude/skills/job_name.step_id/SKILL.md -> job_name.step_id
+            skill_name = self._extract_skill_name(skill_path)
+            if skill_name:
+                permission = f"Skill({skill_name})"
+                if self.add_permission(project_path, permission, settings):
+                    added_count += 1
+
+        # Save if any permissions were added
+        if added_count > 0:
+            self._save_settings(project_path, settings)
+
+        return added_count
+
+    def _extract_skill_name(self, skill_path: Path) -> str | None:
+        """
+        Extract skill name from a skill file path.
+
+        Args:
+            skill_path: Path to skill file (e.g., .claude/skills/job_name/SKILL.md)
+
+        Returns:
+            Skill name (e.g., "job_name") or None if cannot extract
+        """
+        # Handle both absolute and relative paths
+        parts = skill_path.parts
+
+        # Find 'skills' directory and get the next part
+        try:
+            skills_idx = parts.index("skills")
+            if skills_idx + 1 < len(parts):
+                # The skill name is the directory after 'skills'
+                # e.g., skills/job_name/SKILL.md -> job_name
+                return parts[skills_idx + 1]
+        except ValueError:
+            pass
+
+        return None
+
 
 class GeminiAdapter(AgentAdapter):
     """Adapter for Gemini CLI.

deepwork/core/command_executor.py

@@ -159,15 +159,32 @@ def all_commands_succeeded(results: list[CommandResult]) -> bool:
     return all(r.success for r in results)
 
 
-def format_command_errors(results: list[CommandResult]) -> str:
-    """Format error messages from failed commands."""
+def format_command_errors(
+    results: list[CommandResult],
+    rule_name: str | None = None,
+) -> str:
+    """Format detailed error messages from failed commands.
+
+    Args:
+        results: List of command execution results
+        rule_name: Optional rule name to include in error message
+
+    Returns:
+        Formatted error message with command, exit code, stdout, and stderr
+    """
     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)
+            parts: list[str] = []
+            if rule_name:
+                parts.append(f"Rule: {rule_name}")
+            parts.append(f"Command: {result.command}")
+            parts.append(f"Exit code: {result.exit_code}")
+            if result.stdout and result.stdout.strip():
+                parts.append(f"Stdout:\n{result.stdout.strip()}")
+            if result.stderr and result.stderr.strip():
+                parts.append(f"Stderr:\n{result.stderr.strip()}")
+            if not result.stdout.strip() and not result.stderr.strip():
+                parts.append("(no output)")
+            errors.append("\n".join(parts))
+    return "\n\n".join(errors)