ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/claude_permissions.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Bash allow rules for ww's role commands, in Claude Code's local settings.
+
+``init`` offers to write them so an agent running a task is not asked about
+every ``ww`` call.  The rules name the project's wrapper by absolute path,
+never a bare ``ww``: only the project's own launcher is allowed.  Merging adds
+the missing rules and keeps every other key and rule as it was.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ww.errors import StateError
+
+SETTINGS_FILE = ".claude/settings.local.json"
+# The role commands an agent runs; ``discover`` and its variants take no space.
+ROLE_COMMANDS = (
+    "instruction *",
+    "next *",
+    "complete *",
+    "fail *",
+    "dispute *",
+    "check *",
+    "status *",
+    "artifacts *",
+    "items *",
+    "item *",
+    "add-item *",
+    "update-item *",
+    "interact *",
+    "loop *",
+    "lookup *",
+    "discover*",
+    "requirements *",
+)
+
+
+def role_rules(wrapper: Path) -> tuple[str, ...]:
+    """The allow rules for the project wrapper at the absolute path ``wrapper``."""
+    return tuple(f"Bash({wrapper} {command})" for command in ROLE_COMMANDS)
+
+
+def merged(document: dict[str, Any], rules: tuple[str, ...]) -> dict[str, Any]:
+    """``document`` with ``rules`` appended to ``permissions.allow``, none dropped."""
+    permissions = document.get("permissions", {})
+    if not isinstance(permissions, dict):
+        raise StateError("permissions in the settings file must be an object")
+    allowed = permissions.get("allow", [])
+    if not isinstance(allowed, list):
+        raise StateError("permissions.allow in the settings file must be a list")
+    missing = [rule for rule in rules if rule not in allowed]
+    return {
+        **document,
+        "permissions": {**permissions, "allow": [*allowed, *missing]},
+    }
+
+
+def install_rules(root: Path, rules: tuple[str, ...]) -> bool:
+    """Merge ``rules`` into the project's local settings; ``True`` if it changed.
+
+    A file that is not a JSON object is never overwritten: the error names it.
+    """
+    path = root / SETTINGS_FILE
+    document: dict[str, Any] = {}
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise StateError(f"cannot read {SETTINGS_FILE}: {error}") from error
+        if not isinstance(loaded, dict):
+            raise StateError(f"{SETTINGS_FILE} must hold a JSON object")
+        document = loaded
+    updated = merged(document, rules)
+    if updated == document:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(updated, indent=2) + "\n", encoding="utf-8")
+    return True
+
+
+def ensure_ignored(root: Path) -> bool:
+    """Keep the local settings file out of Git; ``True`` if ``.gitignore`` changed."""
+    if _ignored(root):
+        return False
+    gitignore = root / ".gitignore"
+    text = gitignore.read_text(encoding="utf-8") if gitignore.is_file() else ""
+    separator = "\n" if text and not text.endswith("\n") else ""
+    gitignore.write_text(f"{text}{separator}{SETTINGS_FILE}\n", encoding="utf-8")
+    return True
+
+
+def _ignored(root: Path) -> bool:
+    if (root / ".git").exists():
+        try:
+            checked = subprocess.run(
+                ["git", "check-ignore", "-q", SETTINGS_FILE],
+                cwd=root,
+                capture_output=True,
+                check=False,
+            )
+        except OSError:
+            pass
+        else:
+            return checked.returncode == 0
+    gitignore = root / ".gitignore"
+    if not gitignore.is_file():
+        return False
+    lines = {
+        line.strip() for line in gitignore.read_text(encoding="utf-8").splitlines()
+    }
+    return bool(lines & {SETTINGS_FILE, f"/{SETTINGS_FILE}", ".claude/*.local.json"})

ww/cli/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Public command-line entry points for ww."""
+
+from .main import main
+from .parser import build_parser
+
+__all__ = ["build_parser", "main"]

ww/cli/__main__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Run ww's command-line interface as a module."""
+
+from .main import main
+
+raise SystemExit(main())

ww/cli/audit.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Narrow, redacted audit records for each ww invocation."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+from datetime import datetime, timezone
+
+from ww import __version__
+
+
+def _log_record(
+    command: str,
+    workflow: str | None,
+    task_id: str | None,
+    outcome: str,
+    error: str | None,
+    args: argparse.Namespace,
+) -> dict[str, str | None]:
+    return {
+        "invocation_id": args.invocation_id,
+        "timestamp": datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z"),
+        "command": command,
+        "invocation": _invocation(args),
+        "workflow": workflow,
+        "task_id": task_id,
+        "outcome": outcome,
+        # Errors, artifacts, command output, and task state can contain
+        # arbitrary user/provider text. The audit log is intentionally narrow
+        # and never duplicates that text.
+        "error": "protected runtime detail; see task state" if error else None,
+        "error_code": "command_failed" if error else None,
+        "ww_version": __version__,
+        # Who confirmed a gated choice: the operator at a terminal, or an
+        # agent carrying out the operator's decision with --yes.
+        "confirmation": getattr(args, "confirmation", None),
+    }
+
+
+def _invocation(args: argparse.Namespace) -> str:
+    values = ["ww-agentic-workflows", args.command]
+    if args.command == "start":
+        values.extend(["--workflow", args.workflow])
+    task_id = getattr(args, "task_id", None)
+    if (
+        args.command
+        in {
+            "start",
+            "next",
+            "complete",
+            "fail",
+            "status",
+            "instruction",
+            "metadata",
+            "reset",
+        }
+        and task_id
+    ):
+        values.append(task_id)
+    if args.command == "start":
+        for mode in args.modes:
+            values.extend(["--mode", mode])
+        values.extend(
+            [
+                "--agent",
+                args.agent,
+                "--runtime",
+                args.workflow_runtime,
+                "--model",
+                args.model,
+                "--reasoning",
+                args.reasoning,
+            ]
+        )
+    if getattr(args, "role", None) is not None:
+        values.extend(["--role", args.role])
+    if getattr(args, "assignment", None) is not None:
+        values.extend(["--assignment", args.assignment])
+    if args.command == "plan":
+        values.extend(["--workflow", args.workflow, "--agent", args.agent])
+        if args.task_id:
+            values.extend(["--task-id", args.task_id])
+    if args.command == "next":
+        values.extend(["--model", args.model, "--reasoning", args.reasoning])
+        if args.selected_agent:
+            values.extend(["--selected-agent", args.selected_agent])
+        if args.force:
+            values.append("--force")
+        if args.retry:
+            values.append("--retry")
+        if args.force_reason is not None:
+            values.extend(["--reason", "<redacted>"])
+        if args.reassign:
+            values.append("--reassign")
+        if args.replan:
+            values.append("--replan")
+        if args.keep_plan:
+            values.append("--keep-plan")
+        if args.yes:
+            values.append("--yes")
+    if args.command in {"status", "instruction"} and args.run_id:
+        values.extend(["--run", args.run_id])
+    if args.command == "metadata" and args.project:
+        values.append("--project")
+    if args.command == "complete":
+        for key in ("selected_agent", "selected_model", "selected_reasoning"):
+            value = getattr(args, key, None)
+            if value is not None:
+                values.extend(["--" + key.replace("_", "-"), value])
+        for variable in args.variable:
+            values.extend(["--variable", _redacted_variable(variable)])
+        for metadata_value in args.metadata:
+            values.extend(["--metadata", _redacted_variable(metadata_value)])
+    if args.command == "fail":
+        values.extend(["--error", "<redacted>"])
+    if args.command == "reset" and args.yes:
+        values.append("--yes")
+    if getattr(args, "json_output", False):
+        values.append("--json")
+    return shlex.join(values)
+
+
+def _redacted_variable(value: str) -> str:
+    name, separator, _ = value.partition("=")
+    return f"{name}=<redacted>" if separator else "<redacted>"

ww/cli/catalogs.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""JSON catalogs of modes, workflows, runtimes, agents, and extensions."""
+
+from __future__ import annotations
+
+import json
+
+from ww.config import load_configuration, load_modes
+from ww.discovery import AGENT_DIRECTORIES, CUSTOM_AGENT_PREFIX
+from ww.executable import ww_command
+from ww.extensions import ExtensionRegistry
+from ww.runtimes import RUNTIME_INSTRUCTIONS
+from ww.storage import Storage
+
+
+def _catalog_extensions(extensions: ExtensionRegistry) -> str:
+    """Render every discovered extension and what it contributes."""
+    return json.dumps(
+        {
+            "extensions": [
+                {
+                    "id": extension.identifier,
+                    "version": extension.version,
+                    "api_version": extension.api_version,
+                    "source": extensions.identity(extension.identifier).source,
+                    "description": extension.description,
+                    "handlers": [
+                        {
+                            "reference": (
+                                f"ext/{extension.identifier}/handlers:{handler.name}"
+                            ),
+                            "description": handler.description,
+                            "inputs": [value.to_dict() for value in handler.provide],
+                            "outputs": list(handler.outputs),
+                        }
+                        for handler in extension.handlers
+                    ],
+                    "modes": [
+                        {
+                            "reference": (
+                                f"ext/{extension.identifier}/modes:{mode.name}"
+                            ),
+                            "description": list(mode.description),
+                        }
+                        for mode in extension.modes
+                    ],
+                    "commands": [
+                        {
+                            "name": command.name,
+                            "description": command.description,
+                            "usage": (
+                                f"{ww_command()} extension "
+                                f"{extension.identifier} "
+                                f"{command.usage or command.name}"
+                            ),
+                        }
+                        for command in extension.commands
+                    ],
+                    "variable_overrides": [
+                        variable.name for variable in extension.variables
+                    ],
+                }
+                for extension in extensions.extensions
+            ]
+        },
+        indent=2,
+    )
+
+
+def _catalog_modes(storage: Storage, extensions: ExtensionRegistry) -> str:
+    """Render configured and extension modes after validating the workflow file."""
+    modes = load_modes(storage.config_path, extensions)
+    modes.update({mode.name: mode for mode in extensions.qualified_modes()})
+    return json.dumps({"modes": [mode.to_dict() for mode in modes.values()]}, indent=2)
+
+
+def _catalog_workflows(storage: Storage, extensions: ExtensionRegistry) -> str:
+    """Render the configured workflow choices from validated configuration."""
+    configuration = load_configuration(storage.config_path, extensions)
+    return json.dumps(
+        {
+            "workflows": [
+                {
+                    "name": workflow.name,
+                    "description": workflow.description,
+                    "modes": list(workflow.modes),
+                    "runtime": workflow.runtime,
+                }
+                for workflow in configuration.workflows
+            ]
+        },
+        indent=2,
+    )
+
+
+def _catalog_runtimes() -> str:
+    """Render the fixed runtime registry."""
+    return json.dumps(
+        {
+            "runtimes": [
+                {"name": name, "instructions": list(instructions)}
+                for name, instructions in RUNTIME_INSTRUCTIONS.items()
+            ]
+        },
+        indent=2,
+    )
+
+
+def _catalog_projects(extensions: ExtensionRegistry) -> str:
+    """Render the configured projects, the directories tasks may work in."""
+    return json.dumps(
+        {"projects": [project.to_dict() for project in extensions.config.projects]},
+        indent=2,
+    )
+
+
+def _catalog_agents() -> str:
+    """Render supported agent integrations and the custom-agent escape hatch."""
+    return json.dumps(
+        {
+            "agents": [
+                {"name": name, "directory": directory}
+                for name, directory in AGENT_DIRECTORIES.items()
+            ],
+            "custom": {
+                "prefix": CUSTOM_AGENT_PREFIX,
+                "description": "Use custom:<name> for an arbitrary agent name.",
+            },
+        },
+        indent=2,
+    )