opsward 0.0.2__py3-none-any.whl

opsward/__init__.py

@@ -0,0 +1,18 @@
+"""Diagnose, generate, and maintain the AI agent setup of your projects."""
+
+from opsward.base import (
+    AgentInfo,
+    ComponentScore,
+    DiagnosisReport,
+    DocSpec,
+    GeneratedFile,
+    MaintenanceSuggestion,
+    ProjectType,
+    RuleInfo,
+    ScanResult,
+    SkillInfo,
+)
+from opsward.scan import scan
+from opsward.score import diagnose
+from opsward.generate import generate
+from opsward.maintain import maintain

opsward/__main__.py

@@ -0,0 +1,13 @@
+"""CLI entry point: python -m opsward."""
+
+import argh
+
+from opsward.cli import _dispatch_funcs
+
+
+def main():
+    argh.dispatch_commands(_dispatch_funcs)
+
+
+if __name__ == "__main__":
+    main()

opsward/base.py

@@ -0,0 +1,204 @@
+"""All dataclasses and type definitions for opsward."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+class ProjectType(Enum):
+    """Detected project type."""
+
+    python = "python"
+    jsts = "jsts"
+    mixed = "mixed"
+    unknown = "unknown"
+
+
+# ---------------------------------------------------------------------------
+# Inventory items
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SkillInfo:
+    """A skill found in .claude/skills/."""
+
+    name: str
+    path: Path
+    has_skill_md: bool = False
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class AgentInfo:
+    """An agent found in .claude/agents/."""
+
+    name: str
+    path: Path
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class RuleInfo:
+    """A rule found in .claude/rules/."""
+
+    name: str
+    path: Path
+    content: str = ""
+
+
+@dataclass(frozen=True)
+class DocSpec:
+    """A document found in the docs directory."""
+
+    name: str
+    path: Path
+    size_bytes: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Scan output
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ScanResult:
+    """Everything we learned by reading (never writing) a target project."""
+
+    project_root: Path
+    project_type: ProjectType = ProjectType.unknown
+
+    # CLAUDE.md
+    claude_md_path: Optional[Path] = None
+    claude_md_content: str = ""
+
+    # .claude/ inventories
+    skills: list[SkillInfo] = field(default_factory=list)
+    agents: list[AgentInfo] = field(default_factory=list)
+    rules: list[RuleInfo] = field(default_factory=list)
+
+    # Hooks
+    hooks_path: Optional[Path] = None
+    hooks_config: Optional[dict] = None
+
+    # Docs
+    docs: list[DocSpec] = field(default_factory=list)
+    has_docs_guide: bool = False
+    docs_guide_path: Optional[Path] = None
+
+
+# ---------------------------------------------------------------------------
+# Scoring / diagnosis output
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ComponentScore:
+    """Score for a single component (0–100) with optional notes."""
+
+    name: str
+    score: int
+    max_score: int = 100
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DiagnosisReport:
+    """Report card produced by scoring a ScanResult."""
+
+    project_root: Path
+    project_type: ProjectType
+    scores: list[ComponentScore] = field(default_factory=list)
+    missing_items: list[str] = field(default_factory=list)
+    suggestions: list[str] = field(default_factory=list)
+
+    # Weighted overall score (0–100), set by score.py
+    weighted_score: float = 0.0
+
+    @property
+    def overall_score(self) -> float:
+        """Weighted score if set, else simple average."""
+        if self.weighted_score:
+            return self.weighted_score
+        if not self.scores:
+            return 0.0
+        return sum(s.score for s in self.scores) / len(self.scores)
+
+    @property
+    def grade(self) -> str:
+        """Letter grade: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)."""
+        s = self.overall_score
+        if s >= 90:
+            return "A"
+        if s >= 80:
+            return "B"
+        if s >= 70:
+            return "C"
+        if s >= 60:
+            return "D"
+        return "F"
+
+    def __str__(self) -> str:
+        lines = [
+            f"Diagnosis Report: {self.project_root.name}",
+            f"Project type: {self.project_type.value}",
+            f"Overall score: {self.overall_score:.0f}/100  (Grade: {self.grade})",
+            "",
+        ]
+
+        if self.scores:
+            lines.append("Components:")
+            for cs in self.scores:
+                bar = _score_bar(cs.score, cs.max_score)
+                lines.append(f"  {cs.name:<25s} {bar} {cs.score}/{cs.max_score}")
+                for note in cs.notes:
+                    lines.append(f"    - {note}")
+            lines.append("")
+
+        if self.missing_items:
+            lines.append("Missing:")
+            for item in self.missing_items:
+                lines.append(f"  [ ] {item}")
+            lines.append("")
+
+        if self.suggestions:
+            lines.append("Suggestions:")
+            for i, sug in enumerate(self.suggestions, 1):
+                lines.append(f"  {i}. {sug}")
+
+        return "\n".join(lines)
+
+
+def _score_bar(score: int, max_score: int, *, width: int = 20) -> str:
+    """Return a simple ASCII progress bar."""
+    filled = round(width * score / max_score) if max_score else 0
+    return "[" + "#" * filled + "." * (width - filled) + "]"
+
+
+# ---------------------------------------------------------------------------
+# Generation output
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class GeneratedFile:
+    """A file to be written by the generate step."""
+
+    target_path: Path
+    content: str
+    overwrite_policy: str = "skip"  # 'skip' | 'overwrite' | 'merge'
+
+
+# ---------------------------------------------------------------------------
+# Maintenance output
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MaintenanceSuggestion:
+    """A single maintenance action proposed by maintain.py."""
+
+    category: str  # e.g. 'stale_path', 'outdated_doc', 'sync_issue'
+    description: str
+    diff: str = ""

opsward/cli.py

@@ -0,0 +1,211 @@
+"""CLI dispatch for opsward."""
+
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from opsward.base import DiagnosisReport
+from opsward.generate import generate
+from opsward.maintain import maintain
+from opsward.scan import scan
+from opsward.score import diagnose
+
+
+def _serialize_report(report: DiagnosisReport) -> dict:
+    """Convert a DiagnosisReport to a JSON-serialisable dict."""
+    d = asdict(report)
+    d["project_root"] = str(report.project_root)
+    d["project_type"] = report.project_type.value
+    d["overall_score"] = report.overall_score
+    d["grade"] = report.grade
+    return d
+
+
+def diagnose_cmd(
+    *project_roots: str,
+    format: str = "text",
+    verbose: bool = False,
+):
+    """Diagnose the AI agent setup of one or more projects.
+
+    :param project_roots: one or more paths to project directories
+    :param format: output format — 'text' or 'json'
+    :param verbose: show additional detail in text output
+    """
+    if not project_roots:
+        project_roots = (".",)
+
+    reports = []
+    for root_str in project_roots:
+        root = Path(root_str).resolve()
+        if not root.is_dir():
+            print(f"Error: {root_str} is not a directory", file=sys.stderr)
+            sys.exit(2)
+
+        sr = scan(root)
+        report = diagnose(sr)
+        reports.append(report)
+
+    if format == "json":
+        data = [_serialize_report(r) for r in reports]
+        output = data[0] if len(data) == 1 else data
+        print(json.dumps(output, indent=2, default=str))
+    else:
+        for i, report in enumerate(reports):
+            if i > 0:
+                print("\n" + "=" * 60 + "\n")
+            print(report)
+            if verbose:
+                sr = scan(report.project_root)
+                _print_verbose(sr)
+
+    worst = min(r.overall_score for r in reports)
+    sys.exit(0 if worst >= 80 else 1)
+
+
+def generate_cmd(
+    *project_roots: str,
+    write: bool = False,
+    format: str = "text",
+):
+    """Generate missing AI setup artifacts for one or more projects.
+
+    By default, shows what would be created (dry run). Use --write to
+    actually write files. Existing files are never overwritten.
+
+    :param project_roots: one or more paths to project directories
+    :param write: actually write files (default: dry run)
+    :param format: output format — 'text' or 'json'
+    """
+    if not project_roots:
+        project_roots = (".",)
+
+    all_files = []
+    for root_str in project_roots:
+        root = Path(root_str).resolve()
+        if not root.is_dir():
+            print(f"Error: {root_str} is not a directory", file=sys.stderr)
+            sys.exit(2)
+
+        sr = scan(root)
+        files = generate(sr)
+        all_files.extend(files)
+
+        if format == "json":
+            continue
+
+        # Text output
+        if not files:
+            print(f"{root.name}: nothing to generate — all artifacts present")
+            continue
+
+        action = "Creating" if write else "Would create"
+        print(f"{root.name}: {len(files)} artifact(s)\n")
+        for gf in files:
+            rel = _relative_path(gf.target_path, root)
+            exists = gf.target_path.exists()
+            if exists:
+                print(f"  SKIP {rel}  (already exists)")
+            else:
+                print(f"  {action} {rel}")
+
+            if write and not exists:
+                gf.target_path.parent.mkdir(parents=True, exist_ok=True)
+                gf.target_path.write_text(gf.content, encoding="utf-8")
+
+        if not write:
+            print(f"\nDry run — pass --write to create files.")
+
+    if format == "json":
+        data = [
+            {
+                "target_path": str(gf.target_path),
+                "exists": gf.target_path.exists(),
+                "overwrite_policy": gf.overwrite_policy,
+                "content_length": len(gf.content),
+            }
+            for gf in all_files
+        ]
+        print(json.dumps(data, indent=2))
+
+
+def maintain_cmd(
+    *project_roots: str,
+    format: str = "text",
+):
+    """Check for stale references, out-of-sync docs, and other drift.
+
+    :param project_roots: one or more paths to project directories
+    :param format: output format — 'text' or 'json'
+    """
+    if not project_roots:
+        project_roots = (".",)
+
+    all_suggestions = []
+    for root_str in project_roots:
+        root = Path(root_str).resolve()
+        if not root.is_dir():
+            print(f"Error: {root_str} is not a directory", file=sys.stderr)
+            sys.exit(2)
+
+        sr = scan(root)
+        suggestions = maintain(sr)
+        all_suggestions.extend(suggestions)
+
+        if format == "json":
+            continue
+
+        if not suggestions:
+            print(f"{root.name}: no maintenance issues found")
+            continue
+
+        print(f"{root.name}: {len(suggestions)} issue(s)\n")
+        for ms in suggestions:
+            print(f"  [{ms.category}] {ms.description}")
+            if ms.diff:
+                for line in ms.diff.splitlines():
+                    print(f"    {line}")
+        print()
+
+    if format == "json":
+        data = [
+            {
+                "category": ms.category,
+                "description": ms.description,
+                "diff": ms.diff,
+            }
+            for ms in all_suggestions
+        ]
+        print(json.dumps(data, indent=2))
+
+    sys.exit(0 if not all_suggestions else 1)
+
+
+def _relative_path(path: Path, base: Path) -> str:
+    """Return path relative to base, or absolute if not under base."""
+    try:
+        return str(path.relative_to(base))
+    except ValueError:
+        return str(path)
+
+
+def _print_verbose(sr):
+    """Print extra scan details."""
+    print("\nDetailed inventory:")
+    print(f"  Skills:  {len(sr.skills)}")
+    for s in sr.skills:
+        print(f"    - {s.name} (SKILL.md: {'yes' if s.has_skill_md else 'no'})")
+    print(f"  Agents:  {len(sr.agents)}")
+    for a in sr.agents:
+        print(f"    - {a.name}")
+    print(f"  Rules:   {len(sr.rules)}")
+    for r in sr.rules:
+        print(f"    - {r.name}")
+    print(f"  Docs:    {len(sr.docs)}")
+    for d in sr.docs:
+        print(f"    - {d.name} ({d.size_bytes} bytes)")
+    print(f"  Hooks:   {'yes' if sr.hooks_config else 'no'}")
+
+
+_dispatch_funcs = [diagnose_cmd, generate_cmd, maintain_cmd]

opsward/data/templates/jsts/conventions.md

@@ -0,0 +1,30 @@
+# Conventions — ${project_name}
+
+## Code Style
+
+- **Formatter:** ${formatter}
+- **Linter:** ${linter}
+- **Package manager:** ${package_manager}
+
+## Naming
+
+- Files: `camelCase.ts` or `PascalCase.tsx` (components)
+- Functions/variables: `camelCase`
+- Classes/components: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Types/interfaces: `PascalCase`
+
+## Imports
+
+- Use named exports over default exports
+- Group imports: external, then internal, then relative
+
+## TypeScript
+
+- Enable strict mode
+- Prefer `interface` over `type` for object shapes
+- Use `const` assertions where applicable
+
+## Project-Specific Conventions
+
+<!-- Add conventions specific to this project -->

opsward/data/templates/jsts/testing.md

@@ -0,0 +1,28 @@
+# Testing — ${project_name}
+
+## Test Framework
+
+${test_framework}
+
+## Running Tests
+
+```bash
+${test_command}
+```
+
+## Test Structure
+
+- Tests live alongside source files or in `${test_dir}/`
+- Test files follow `*.test.ts` or `*.spec.ts` naming
+
+## Coverage
+
+```bash
+${coverage_command}
+```
+
+## Writing Tests
+
+- Each test block tests one behavior
+- Use descriptive test names
+- Prefer `describe` / `it` structure for grouping

opsward/data/templates/python/conventions.md

@@ -0,0 +1,33 @@
+# Conventions — ${project_name}
+
+## Code Style
+
+- **Formatter:** ${formatter}
+- **Linter:** ${linter}
+- **Line length:** ${line_length}
+
+## Naming
+
+- Modules: `snake_case`
+- Classes: `PascalCase`
+- Functions/variables: `snake_case`
+- Constants: `UPPER_SNAKE_CASE`
+
+## Imports
+
+- Standard library first, then third-party, then local
+- Prefer absolute imports
+
+## Type Hints
+
+- Use type hints for all public function signatures
+- Prefer `collections.abc` types (`Mapping`, `Iterable`, `Sequence`) over concrete types
+
+## Testing
+
+- Tests in `tests/` with `test_{module_name}.py` naming
+- Use pytest fixtures for shared setup
+
+## Project-Specific Conventions
+
+<!-- Add conventions specific to this project -->

opsward/data/templates/python/testing.md

@@ -0,0 +1,29 @@
+# Testing — ${project_name}
+
+## Test Framework
+
+${test_framework}
+
+## Running Tests
+
+```bash
+${test_command}
+```
+
+## Test Structure
+
+- Tests live in `${test_dir}/`
+- Test files follow `test_{module_name}.py` naming
+- Fixtures and shared helpers in `${test_dir}/conftest.py`
+
+## Coverage
+
+```bash
+${coverage_command}
+```
+
+## Writing Tests
+
+- Each test function tests one behavior
+- Use descriptive test names: `test_{what}_{condition}_{expected}`
+- Prefer pytest fixtures over setUp/tearDown

opsward/data/templates/shared/architecture.md

@@ -0,0 +1,21 @@
+# Architecture
+
+## Overview
+
+${project_name} — ${project_description}
+
+## Tech Stack
+
+${tech_stack}
+
+## Module Map
+
+${module_map}
+
+## Data Flow
+
+<!-- Describe the primary data flow through the system -->
+
+## Key Invariants
+
+<!-- List any important invariants that must be maintained -->

opsward/data/templates/shared/claude_md.md

@@ -0,0 +1,28 @@
+# ${project_name}
+
+${project_description}
+
+## Project Overview
+
+${project_name} is a ${project_type} project.
+
+## Tech Stack
+
+${tech_stack}
+
+## Documentation
+
+For detailed project knowledge, see `${docs_path}/docs_guide.md`.
+Read it to discover which docs to consult for your current task.
+
+## Module Map
+
+${module_map}
+
+## Commands
+
+${commands}
+
+## Conventions
+
+${conventions}

opsward/data/templates/shared/decisions/0000-template.md

@@ -0,0 +1,17 @@
+# NNNN — Title of Decision
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-title.md)
+
+## Context
+
+<!-- What is the issue motivating this decision? -->
+
+## Decision
+
+<!-- What is the change being proposed? -->
+
+## Consequences
+
+<!-- What are the positive and negative consequences of this decision? -->

opsward/data/templates/shared/dependencies.md

@@ -0,0 +1,17 @@
+# External Dependencies — ${project_name}
+
+Services, APIs, and system-level dependencies beyond the package manager.
+
+## Environment Variables
+
+| Variable | Purpose | Required |
+|----------|---------|----------|
+${env_vars_table}
+
+## External Services
+
+<!-- List any APIs, databases, or third-party services the project depends on -->
+
+## System Dependencies
+
+<!-- List any system packages, binaries, or tools required beyond the language runtime -->

opsward/data/templates/shared/deployment.md

@@ -0,0 +1,17 @@
+# Deployment — ${project_name}
+
+## Environments
+
+<!-- List deployment environments (dev, staging, production) -->
+
+## How to Deploy
+
+<!-- Step-by-step deployment instructions -->
+
+## CI/CD Pipeline
+
+<!-- Describe the continuous integration and deployment pipeline -->
+
+## Rollback Procedure
+
+<!-- How to roll back a bad deployment -->