salesforce-agent-optimizer 1.0.0__py3-none-any.whl

salesforce_agent_optimizer/__init__.py

@@ -0,0 +1,23 @@
+"""Salesforce Agent Optimizer package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+PACKAGE_NAME = "salesforce-agent-optimizer"
+
+
+def get_version() -> str:
+    """Return the installed package version."""
+    try:
+        return version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        source_version = Path(__file__).resolve().parents[2] / "VERSION"
+        if source_version.exists():
+            return source_version.read_text(encoding="utf-8").strip()
+        return "0.0.0+local"
+
+
+__version__ = get_version()

salesforce_agent_optimizer/cli.py

@@ -0,0 +1,211 @@
+"""Command-line interface for Salesforce Agent Optimizer."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .doctor import format_report, report_to_json, run_doctor
+from .installer import install, project_destination, uninstall, update, user_destination
+from .knowledge import format_knowledge_report, run_knowledge
+from .validation import validate_auto
+from .version_context import (
+    format_report as format_version_context_report,
+    scaffold as version_context_scaffold,
+    update as version_context_update,
+    validate as version_context_validate,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="sfao", description="Salesforce Agent Optimizer CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    install_parser = subparsers.add_parser("install", help="Install agent skill files")
+    install_parser.add_argument("--project", action="store_true", help="Install into the current repository")
+    install_parser.add_argument(
+        "--platform",
+        choices=["codex", "claude", "copilot", "all"],
+        default="all",
+        help="Agent platform to install",
+    )
+    install_parser.add_argument("--target", type=Path, help="Override installation root")
+    install_parser.add_argument("--json", action="store_true", help="Emit compact JSON")
+
+    update_parser = subparsers.add_parser("update", help="Update generated installed files")
+    update_parser.add_argument("--project", action="store_true", help="Update files in the current repository")
+    update_parser.add_argument(
+        "--platform",
+        choices=["codex", "claude", "copilot", "all"],
+        default="all",
+        help="Agent platform to update",
+    )
+    update_parser.add_argument("--target", type=Path, help="Override installation root")
+    update_parser.add_argument("--json", action="store_true", help="Emit compact JSON")
+
+    uninstall_parser = subparsers.add_parser("uninstall", help="Remove generated installed files")
+    uninstall_parser.add_argument("--project", action="store_true", help="Remove files in the current repository")
+    uninstall_parser.add_argument(
+        "--platform",
+        choices=["codex", "claude", "copilot", "all"],
+        default="all",
+        help="Agent platform to uninstall",
+    )
+    uninstall_parser.add_argument("--target", type=Path, help="Override installation root")
+    uninstall_parser.add_argument("--yes", action="store_true", help="Confirm non-interactive uninstall")
+    uninstall_parser.add_argument("--json", action="store_true", help="Emit compact JSON")
+
+    doctor_parser = subparsers.add_parser("doctor", help="Diagnose environment and installed files")
+    doctor_parser.add_argument("--json", action="store_true", help="Emit JSON")
+    doctor_parser.add_argument("--root", type=Path, default=Path.cwd(), help="Root to inspect")
+    doctor_parser.add_argument("--summary", action="store_true", help="Emit compact summary")
+    doctor_parser.add_argument("--compact", action="store_true", help="Emit compact summary")
+    doctor_parser.add_argument("--verbose", action="store_true", help="Emit full diagnostics")
+
+    validate_parser = subparsers.add_parser("validate", help="Validate source tree or installation")
+    validate_parser.add_argument("--json", action="store_true", help="Emit JSON")
+    validate_parser.add_argument("--root", type=Path, default=Path.cwd(), help="Root to validate")
+    validate_parser.add_argument("--summary", action="store_true", help="Emit compact summary")
+    validate_parser.add_argument("--compact", action="store_true", help="Emit compact summary")
+    validate_parser.add_argument("--verbose", action="store_true", help="Emit validation details")
+
+    knowledge_parser = subparsers.add_parser("knowledge", help="Manage local Salesforce Knowledge")
+    knowledge_subparsers = knowledge_parser.add_subparsers(dest="knowledge_command", required=True)
+    for name in ("init", "refresh", "doctor"):
+        parser_for_command = knowledge_subparsers.add_parser(name, help=f"Knowledge {name}")
+        parser_for_command.add_argument("--project-root", type=Path, default=Path.cwd())
+        parser_for_command.add_argument("--target-org", help="Explicit org alias for optional enrichment")
+        parser_for_command.add_argument("--json", action="store_true", help="Emit compact JSON")
+        parser_for_command.add_argument("--summary", action="store_true", help="Emit compact summary")
+        parser_for_command.add_argument("--compact", action="store_true", help="Emit compact summary")
+        parser_for_command.add_argument("--verbose", action="store_true", help="Emit changed paths")
+        parser_for_command.add_argument("--max-items", type=int, help="Limit indexed entries")
+
+    version_context_parser = subparsers.add_parser(
+        "version-context",
+        help="Manage Salesforce release and API version context",
+    )
+    version_context_subparsers = version_context_parser.add_subparsers(
+        dest="version_context_command",
+        required=True,
+    )
+    for name in ("scaffold", "update", "validate"):
+        parser_for_command = version_context_subparsers.add_parser(
+            name,
+            help=f"Version-context {name}",
+        )
+        parser_for_command.add_argument("--root", type=Path, default=Path.cwd())
+        parser_for_command.add_argument("--json", action="store_true", help="Emit compact JSON")
+        parser_for_command.add_argument("--summary", action="store_true", help="Emit compact summary")
+        parser_for_command.add_argument("--compact", action="store_true", help="Emit compact summary")
+        parser_for_command.add_argument("--verbose", action="store_true", help="Emit details")
+        if name == "update":
+            parser_for_command.add_argument(
+                "--offline",
+                action="store_true",
+                help="Use existing official-source context without network checks",
+            )
+
+    subparsers.add_parser("version", help="Print package version")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "version":
+        print(f"salesforce-agent-optimizer {__version__}")
+        return 0
+    if args.command == "install":
+        target = args.target or (project_destination() if args.project else user_destination())
+        report = install(target, project=args.project, platform=args.platform)
+        print_operation_summary("install", report, json_output=args.json)
+        return 0 if report.ok else 1
+    if args.command == "update":
+        target = args.target or (project_destination() if args.project else user_destination())
+        report = update(target, project=args.project, platform=args.platform)
+        print_operation_summary("update", report, json_output=args.json)
+        return 0 if report.ok else 1
+    if args.command == "uninstall":
+        target = args.target or (project_destination() if args.project else user_destination())
+        report = uninstall(target, project=args.project, platform=args.platform, yes=args.yes)
+        print_operation_summary("uninstall", report, json_output=args.json)
+        return 0 if report.ok else 1
+    if args.command == "doctor":
+        report = run_doctor(args.root)
+        print(report_to_json(report) if args.json else format_report(report, verbose=args.verbose), end="")
+        return 1 if report.has_errors else 0
+    if args.command == "validate":
+        result = validate_auto(args.root, expected_version=__version__)
+        if args.json:
+            print(json.dumps(result.to_dict(), separators=(",", ":"), sort_keys=True))
+        else:
+            output = format_validation_result(result, verbose=args.verbose)
+            stream = sys.stdout if result.ok else sys.stderr
+            print(output, end="", file=stream)
+        return 0 if result.ok else 1
+    if args.command == "knowledge":
+        report = run_knowledge(
+            args.knowledge_command,
+            args.project_root,
+            target_org=args.target_org,
+            max_items=args.max_items,
+        )
+        if args.json:
+            print(json.dumps(report.to_dict(), separators=(",", ":"), sort_keys=True))
+        else:
+            print(format_knowledge_report(report, verbose=args.verbose), end="")
+        return 0 if report.ok else 1
+    if args.command == "version-context":
+        if args.version_context_command == "scaffold":
+            report = version_context_scaffold(args.root)
+        elif args.version_context_command == "update":
+            report = version_context_update(args.root, offline=args.offline)
+        else:
+            report = version_context_validate(args.root)
+        if args.json:
+            print(json.dumps(report.to_dict(), separators=(",", ":"), sort_keys=True))
+        else:
+            print(format_version_context_report(report, verbose=args.verbose), end="")
+        return 0 if report.ok else 1
+    parser.print_help()
+    return 2
+
+
+def format_validation_result(result, verbose: bool = False) -> str:
+    status = "OK" if result.ok else "ERROR"
+    lines = [f"Salesforce Agent Optimizer validation: {status}"]
+    if result.warnings or result.errors:
+        for error in result.errors:
+            lines.append(f"ERROR: {error}")
+        for warning in result.warnings:
+            lines.append(f"WARN: {warning}")
+    else:
+        lines.append("No warnings or errors.")
+    if verbose and result.ok:
+        lines.append("Validated required files, versions, frontmatter, YAML, TOML, JSON, Python, and text shape.")
+    return "\n".join(lines) + "\n"
+
+
+def print_operation_summary(action: str, report, json_output: bool = False) -> None:
+    if json_output:
+        print(json.dumps(report.to_dict(), separators=(",", ":"), sort_keys=True))
+        return
+    print(f"Salesforce Agent Optimizer {action} summary")
+    for label in ("installed", "updated", "removed", "skipped", "stale", "warnings", "errors"):
+        values = getattr(report, label)
+        print(f"{label.title()}: {len(values)}")
+        for item in values[:20]:
+            print(f"- {item}")
+        if len(values) > 20:
+            print(f"- ... {len(values) - 20} more")
+    print("Next steps:")
+    print("- Run: sfao doctor")
+    print("- Run: sfao validate")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

salesforce_agent_optimizer/doctor.py

@@ -0,0 +1,172 @@
+"""Environment diagnostics for Salesforce Agent Optimizer."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import site
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .validation import SKILL_NAME, validate_auto
+
+
+@dataclass
+class Check:
+    name: str
+    status: str
+    detail: str = ""
+
+
+@dataclass
+class DoctorReport:
+    sections: dict[str, list[Check]] = field(default_factory=dict)
+
+    def add(self, section: str, name: str, status: str, detail: str = "") -> None:
+        self.sections.setdefault(section, []).append(Check(name, status, detail))
+
+    @property
+    def has_errors(self) -> bool:
+        return any(check.status == "ERROR" for checks in self.sections.values() for check in checks)
+
+    @property
+    def has_warnings(self) -> bool:
+        return any(check.status == "WARN" for checks in self.sections.values() for check in checks)
+
+    @property
+    def status(self) -> str:
+        if self.has_errors:
+            return "ERROR"
+        if self.has_warnings:
+            return "WARN"
+        return "OK"
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"ok": not self.has_errors, "status": self.status}
+        payload.update(
+            {
+                section: [check.__dict__ for check in checks]
+                for section, checks in self.sections.items()
+            }
+        )
+        return payload
+
+
+def run_doctor(root: Path | None = None) -> DoctorReport:
+    root = (root or Path.cwd()).resolve()
+    report = DoctorReport()
+    report.add("Core", "Package", "OK", f"salesforce-agent-optimizer v{__version__}")
+    py_status = "OK" if sys.version_info >= (3, 10) else "ERROR"
+    report.add("Core", "Python", py_status, platform.python_version())
+    report.add("Core", "OS", "OK", platform.system() or sys.platform)
+    report.add("Core", "Git", "OK" if shutil.which("git") else "WARN", shutil.which("git") or "not found")
+    report.add(
+        "Core",
+        "Salesforce CLI sf",
+        "OK" if shutil.which("sf") else "WARN",
+        shutil.which("sf") or "not found",
+    )
+    report.add(
+        "Core",
+        "Git repository",
+        "OK" if is_git_repo(root) else "WARN",
+        str(root),
+    )
+    report.add(
+        "Core",
+        "Salesforce DX project",
+        "OK" if (root / "sfdx-project.json").exists() else "WARN",
+        "sfdx-project.json found" if (root / "sfdx-project.json").exists() else "not found",
+    )
+    report.add(
+        "Agent adapters",
+        "Codex skill",
+        "OK" if (root / ".agents" / "skills" / SKILL_NAME / "SKILL.md").exists() else "WARN",
+        ".agents/skills/salesforce-agent-optimizer",
+    )
+    report.add(
+        "Agent adapters",
+        "Claude skill",
+        "OK" if (root / ".claude" / "skills" / SKILL_NAME / "SKILL.md").exists() else "WARN",
+        ".claude/skills/salesforce-agent-optimizer",
+    )
+    copilot_ok = (root / ".github" / "copilot-instructions.md").exists() and (
+        root / ".github" / "instructions" / "salesforce-agent-optimizer.instructions.md"
+    ).exists()
+    report.add("Agent adapters", "GitHub Copilot instructions", "OK" if copilot_ok else "WARN")
+    report.add("Agent adapters", "AGENTS.md", "OK" if (root / "AGENTS.md").exists() else "WARN")
+    validation = validate_auto(root, expected_version=__version__)
+    report.add(
+        "Validation",
+        "Skill package",
+        "OK" if validation.ok else "ERROR",
+        "valid" if validation.ok else "; ".join(validation.errors[:3]),
+    )
+    if validation.warnings:
+        report.add("Validation", "Warnings", "WARN", "; ".join(validation.warnings[:3]))
+    report.add("Validation", "Version alignment", "OK" if validation.ok else "ERROR", f"v{__version__}")
+    if platform.system().lower().startswith("windows"):
+        report.add("Windows", "PATH", "OK" if user_scripts_on_path() else "WARN", windows_path_detail())
+    return report
+
+
+def is_git_repo(root: Path) -> bool:
+    completed = subprocess.run(
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+        text=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    return completed.returncode == 0
+
+
+def user_scripts_on_path() -> bool:
+    scripts = Path(site.USER_BASE) / "Scripts"
+    path_parts = [Path(part) for part in (os.environ.get("PATH") or "").split(os.pathsep) if part]
+    return any(part == scripts for part in path_parts)
+
+
+def windows_path_detail() -> str:
+    scripts = Path(site.USER_BASE) / "Scripts"
+    return f"{scripts} is {'on' if user_scripts_on_path() else 'not on'} PATH"
+
+
+def format_report(report: DoctorReport, verbose: bool = False) -> str:
+    lines = [f"Salesforce Agent Optimizer Doctor: {report.status}"]
+    if not verbose:
+        issues = [
+            (section, check)
+            for section, checks in report.sections.items()
+            for check in checks
+            if check.status in {"WARN", "ERROR"}
+        ]
+        if issues:
+            lines.append("Warnings and errors:")
+            for section, check in issues:
+                detail = f" {check.detail}" if check.detail else ""
+                lines.append(f"- {section} / {check.name}: {check.status}{detail}")
+        else:
+            lines.append("No warnings or errors.")
+        lines.append("Use --verbose for full diagnostics.")
+        return "\n".join(lines).rstrip() + "\n"
+    lines.append("")
+    for section, checks in report.sections.items():
+        lines.append(f"{section}:")
+        for check in checks:
+            detail = f" {check.detail}" if check.detail else ""
+            lines.append(f"- {check.name}: {check.status}{detail}")
+        lines.append("")
+    lines.append("Status:")
+    lines.append("Everything looks good." if not report.has_errors else "Problems found.")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def report_to_json(report: DoctorReport) -> str:
+    return json.dumps(report.to_dict(), separators=(",", ":"), sort_keys=True) + "\n"