agent-devkit 0.1.6 → 0.2.0

package/runtime/agents/selenium-automation-builder/knowledge/context.md

@@ -0,0 +1,15 @@
+# Context
+
+Selenium deve ser escolhido quando existe requisito WebDriver, Selenium Grid,
+browser remoto corporativo, projeto legado, extensoes de browser ou padrao de
+equipe ja estabelecido.
+
+Playwright continua sendo preferencia para automacao web moderna quando nao ha
+necessidade de WebDriver.
+
+Classificacao de side effects:
+
+- `read-only`: navegacao, leitura e captura sem alterar estado.
+- `form-submit`: envio de formulario ou clique de salvamento.
+- `external-write`: alteracao em sistema externo.
+- `destructive`: exclusao, compra, cancelamento ou acao irreversivel.

package/runtime/agents/selenium-automation-builder/knowledge/policies.yaml

@@ -0,0 +1,17 @@
+policies:
+  supported_scope: selenium-webdriver-automation
+  selenium_reasons:
+    - existing-selenium
+    - selenium-grid
+    - remote-browser
+    - webdriver-required
+    - legacy-project
+    - browser-extension
+    - team-standard
+    - playwright-not-allowed
+  playwright_preference: problem 27
+  default_write_mode: dry_run
+  external_side_effects: blocked_by_default
+  secrets: never_persist
+  waits: explicit_webdriverwait_required
+  sleep: forbidden_as_primary_wait

package/runtime/agents/selenium-automation-builder/knowledge/system.md

@@ -0,0 +1,18 @@
+# System
+
+Voce e o `selenium-automation-builder`, especialista em automacoes
+Selenium/WebDriver.
+
+Seu trabalho e gerar automacoes Selenium apenas quando houver motivo tecnico
+claro. Quando Playwright for mais adequado, recomende o problema 27 em vez de
+forcar Selenium.
+
+## Regras Principais
+
+- Exigir justificativa para Selenium.
+- Usar `WebDriverWait` e expected conditions.
+- Evitar `time.sleep`.
+- Incluir `--dry-run`, `--execute`, `--confirm`, `--headless`, `--browser`,
+  `--remote-url`, `--timeout` e `--screenshot-dir`.
+- Capturar screenshot em falha.
+- Nao hardcodar credenciais.

package/runtime/agents/selenium-automation-builder/templates/capability-wrapper.md

@@ -0,0 +1,4 @@
+# Capability Wrapper
+
+Arquivos planejados para empacotar uma automacao Selenium como capability do
+Agent DevKit.

package/runtime/agents/selenium-automation-builder/templates/selenium-automation.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Generated Selenium automation template."""
+
+import argparse
+import json
+import logging
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--execute", action="store_true")
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+    print(json.dumps({"dry_run": not args.execute}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/selenium-automation-builder/templates/selenium-readme.md

@@ -0,0 +1,13 @@
+# Selenium Automation README
+
+## Uso
+
+```bash
+python selenium_automation.py --dry-run
+```
+
+## Guardrails
+
+- Selenium exige justificativa.
+- Usar waits explicitos.
+- Escrita real exige confirmacao.

package/runtime/agents/selenium-automation-builder/templates/selenium-review-report.md

@@ -0,0 +1,13 @@
+# Selenium Automation Review
+
+## Resultado
+
+- Status:
+
+## Findings
+
+-
+
+## Riscos
+
+-

package/runtime/agents/selenium-automation-builder/templates/selenium-test.py

@@ -0,0 +1,9 @@
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_selenium_automation_dry_run():
+    script = Path(__file__).resolve().parents[1] / "selenium_automation.py"
+    result = subprocess.run([sys.executable, str(script), "--dry-run"], text=True, capture_output=True)
+    assert result.returncode == 0

package/runtime/agents/selenium-automation-builder/tests/test_runners.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Tests for the Selenium Automation Builder runners."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import py_compile
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+AGENT = ROOT / "agent"
+AGENT_DIR = ROOT / "agents" / "selenium-automation-builder"
+REPOSITORY_PATH = AGENT_DIR / "infra" / "integrations" / "selenium-automation" / "selenium_automation_repository.py"
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("selenium_automation_repository", REPOSITORY_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load repository from {REPOSITORY_PATH}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class SeleniumAutomationBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_spec(
+        self,
+        root: Path,
+        *,
+        automation_name: str = "Legacy Login Check",
+        target_project: Path | None = None,
+        selenium_reasons: list[str] | None = None,
+        purpose: str = "Check a legacy login page through WebDriver-compatible browser automation.",
+        side_effects: str = "read-only",
+    ) -> Path:
+        path = root / "selenium-spec.yaml"
+        target_project_line = f"target_project: {target_project}\n" if target_project else ""
+        reasons = ["webdriver-required"] if selenium_reasons is None else selenium_reasons
+        reason_block = "selenium_reasons: []" if not reasons else "selenium_reasons:\n" + "\n".join(f"  - {item}" for item in reasons)
+        path.write_text(
+            f"""
+automation_name: {automation_name}
+{target_project_line}purpose: {purpose}
+target_url: https://example.test/login
+browser: chrome
+remote_url_env: SELENIUM_REMOTE_URL
+auth_strategy: env
+side_effects: {side_effects}
+{reason_block}
+selectors:
+  - name: username
+    by: css
+    value: '[name="username"]'
+  - name: submit
+    by: css
+    value: 'button[type="submit"]'
+steps:
+  - open target_url
+  - wait for username
+  - capture status
+quality_gates:
+  - explicit waits are used
+  - screenshot is captured on failure
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_plan_selenium_automation_returns_plan_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.plan_selenium_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["automation"]["slug"], "legacy-login-check")
+            self.assertEqual(result["browser"], "chrome")
+            self.assertEqual(result["write_policy"], "read_only")
+            planned_paths = {item["path"] for item in result["planned_artifacts"]}
+            self.assertIn("selenium_automation.py", planned_paths)
+            self.assertFalse((root / "selenium_automation.py").exists())
+
+    def test_plan_selenium_automation_reports_needs_input(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = root / "selenium-spec.yaml"
+            spec_path.write_text("automation_name: incomplete\n", encoding="utf-8")
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.plan_selenium_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-input")
+            self.assertGreaterEqual(
+                set(result["missing_fields"]),
+                {"purpose", "browser", "selectors", "steps", "auth_strategy", "side_effects", "selenium_reasons"},
+            )
+
+    def test_plan_recommends_playwright_when_selenium_not_justified(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, selenium_reasons=[])
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.plan_selenium_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-playwright-review")
+            self.assertEqual(result["reason"], "selenium_not_justified")
+            self.assertIn("problem 27", " ".join(result["next_steps"]).lower())
+
+    def test_plan_blocks_secret_marker(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, purpose="Login with PASSWORD=abc in the page.")
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.plan_selenium_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "forbidden_sensitive_marker")
+
+    def test_generate_selenium_script_contains_required_guardrails(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.generate_selenium_script(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            content = result["content"]
+            self.assertIn("WebDriverWait", content)
+            self.assertIn("--headless", content)
+            self.assertIn("--browser", content)
+            self.assertIn("--remote-url", content)
+            self.assertIn("--dry-run", content)
+            self.assertIn("--confirm", content)
+            self.assertIn("save_screenshot", content)
+            self.assertNotIn("time.sleep", content)
+            py_compile.compile(str(self.write_temp_script(root, content)), doraise=True)
+
+    def test_generate_selenium_project_files_dry_run_does_not_write(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target-project"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.generate_selenium_project_files(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "planned")
+            self.assertTrue(result["dry_run"])
+            planned_paths = {item["path"] for item in result["planned_files"]}
+            self.assertGreaterEqual(
+                planned_paths,
+                {
+                    "legacy-login-check/selenium_automation.py",
+                    "legacy-login-check/README.md",
+                    "legacy-login-check/tests/test_selenium_automation.py",
+                },
+            )
+            self.assertFalse((target_project / "legacy-login-check").exists())
+
+    def test_generate_selenium_project_files_execute_writes_inside_target_project(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target-project"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.generate_selenium_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "written")
+            self.assertTrue((target_project / "legacy-login-check" / "selenium_automation.py").exists())
+            for item in result["written_files"]:
+                path = Path(item["path"]).resolve()
+                self.assertTrue(path.is_relative_to(target_project.resolve()), item["path"])
+
+    def test_generate_selenium_project_files_blocks_overwrite_without_permission(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target-project"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+            repository.generate_selenium_project_files(spec_path=spec_path, execute=True)
+
+            result = repository.generate_selenium_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "target_exists")
+
+    def test_review_selenium_script_detects_missing_explicit_waits(self) -> None:
+        repository = self.repository_module.SeleniumAutomationRepository(root=ROOT)
+
+        result = repository.review_selenium_script(text="driver.find_element('css selector', '#x')", side_effects="read-only")
+
+        self.assertFalse(result["valid"])
+        self.assertEqual(result["status"], "failed")
+        self.assertTrue(any("webdriverwait" in finding.lower() for finding in result["findings"]))
+
+    def test_review_selenium_script_accepts_generated_script(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+            script = repository.generate_selenium_script(spec_path=spec_path)["content"]
+
+            result = repository.review_selenium_script(text=script, side_effects="read-only")
+
+            self.assertTrue(result["valid"], result["findings"])
+            self.assertEqual(result["findings"], [])
+
+    def test_wrap_selenium_as_capability_execute_writes_compilable_runner(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target-project"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.SeleniumAutomationRepository(root=root)
+
+            result = repository.wrap_selenium_as_capability(
+                spec_path=spec_path,
+                agent_id="web-ops-agent",
+                capability_id="legacy-login-check",
+                execute=True,
+            )
+
+            self.assertEqual(result["status"], "written")
+            runner = target_project / "agents" / "web-ops-agent" / "capabilities" / "legacy-login-check" / "runner.py"
+            self.assertTrue(runner.exists())
+            py_compile.compile(str(runner), doraise=True)
+
+    def test_plan_selenium_automation_runner_is_executable_through_agent_cli(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            spec_path = self.write_spec(Path(tmpdir))
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(AGENT),
+                    "--json",
+                    "run",
+                    "selenium-automation-builder",
+                    "plan-selenium-automation",
+                    "--spec",
+                    str(spec_path),
+                ],
+                cwd=ROOT,
+                check=False,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=60,
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr or result.stdout)
+        payload = json.loads(result.stdout)
+        runner_payload = json.loads(payload["stdout"])
+        self.assertEqual(runner_payload["status"], "ok")
+        self.assertEqual(runner_payload["automation"]["slug"], "legacy-login-check")
+
+    def write_temp_script(self, root: Path, content: str) -> Path:
+        script = root / "selenium_automation.py"
+        script.write_text(content, encoding="utf-8")
+        return script
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/software-specification-analyst/agent.yaml

@@ -48,8 +48,21 @@ agent_surface:
     - ../../vendor/skills/CATALOG.md
 
 write_policy:
-  read_operations: auto
-  project_analysis: ask_before_creating_output_directory
-  specification_generation: ask_before_creating_output_directory
+  read_operations: read_only
+  project_analysis: output_only
+  specification_generation: output_only
   overwrite_operations: confirm
-  external_side_effects: unsupported
+  external_side_effects: blocked_by_default
+
+routing:
+  anchors:
+    - demanda
+    - especificacao
+    - historia
+    - requirements
+    - requisitos
+    - specification
+    - stories
+  intents:
+    - specification.analysis
+  priority: 60

package/runtime/agents/software-specification-analyst/capabilities/analyze-multiple-projects/capability.yaml

@@ -18,4 +18,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/software-specification-analyst/capabilities/analyze-project-context/capability.yaml

@@ -29,4 +29,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/software-specification-analyst/capabilities/conduct-requirements-interview/capability.yaml

@@ -23,4 +23,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/software-specification-analyst/capabilities/create-complete-spec/capability.yaml

@@ -39,4 +39,4 @@ integration:
   repository: null
   methods: []
 
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/software-specification-analyst/capabilities/create-final-spec-from-analysis/capability.yaml

@@ -25,4 +25,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/software-specification-analyst/capabilities/create-functional-spec/capability.yaml

@@ -19,3 +19,14 @@ integration:
   repository: null
   methods: []
 write_policy: read_only
+
+routing:
+  anchors:
+    - especificacao funcional
+    - functional spec
+    - regra de negocio
+  intents:
+    - spec.functional
+  examples:
+    - gere uma especificacao funcional
+  priority: 80

package/runtime/agents/software-specification-analyst/capabilities/create-technical-spec/capability.yaml

@@ -19,3 +19,15 @@ integration:
   repository: null
   methods: []
 write_policy: read_only
+
+routing:
+  anchors:
+    - arquitetura
+    - especificacao tecnica
+    - spec tecnica
+    - technical spec
+  intents:
+    - spec.technical
+  examples:
+    - gere uma especificacao tecnica para essa demanda
+  priority: 80

package/runtime/agents/software-specification-analyst/capabilities/refine-analysis-with-feedback/capability.yaml

@@ -23,4 +23,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/software-specification-analyst/capabilities/write-user-stories/capability.yaml

@@ -19,3 +19,15 @@ integration:
   repository: null
   methods: []
 write_policy: read_only
+
+routing:
+  anchors:
+    - criterios de aceite
+    - historia
+    - user stories
+    - user story
+  intents:
+    - spec.user-stories
+  examples:
+    - escreva historias de usuario
+  priority: 80

package/runtime/agents/sqlserver-change-operator/agent.yaml

@@ -61,6 +61,17 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
+  read_operations: read_only
   write_operations: confirm
   destructive_operations: blocked_by_default
+
+routing:
+  anchors:
+    - banco
+    - migracao
+    - migration
+    - sql
+    - sqlserver
+  intents:
+    - database.sqlserver.change
+  priority: 35

package/runtime/agents/sqlserver-data-analyzer/agent.yaml

@@ -85,5 +85,16 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
-  write_operations: unsupported
+  read_operations: read_only
+  write_operations: blocked_by_default
+
+routing:
+  anchors:
+    - banco
+    - database
+    - sql
+    - sqlserver
+    - tabela
+  intents:
+    - database.sqlserver.analysis
+  priority: 45

package/runtime/agents/supabase-project-analyst/AGENTS.md

@@ -0,0 +1,29 @@
+# Supabase Project Analyst
+
+Instrucoes locais para trabalhar no agente `supabase-project-analyst`.
+
+## Responsabilidade
+
+Este agente analisa projetos Supabase em modo read-only, com foco em Postgres,
+RLS, Auth, Storage, Edge Functions, migrations, performance e seguranca. A
+primeira fase analisa arquivos locais e readiness de CLI/MCP sem aplicar SQL.
+
+## Fora De Escopo
+
+- Aplicar migrations.
+- Executar SQL real.
+- Criar projeto Supabase.
+- Alterar RLS, Auth, Storage ou configuracao remota.
+- Armazenar credenciais OAuth/token.
+- Substituir `postgres-data-analyzer` para analise SQL generica.
+
+## Guardrails
+
+- Nunca imprimir `service_role`, access token, DB URL ou JWT secret.
+- Nunca usar `raw_user_meta_data`/`user_metadata` como autorizacao segura.
+- Alertar para tabelas expostas sem RLS.
+- Alertar para `auth.role()`, `TO authenticated` sem ownership e UPDATE sem
+  `WITH CHECK`.
+- Alertar para `SECURITY DEFINER` em schema exposto e views sem
+  `security_invoker`.
+- Gerar SQL apenas como sugestao, nunca aplicar.

package/runtime/agents/supabase-project-analyst/README.md

@@ -0,0 +1,23 @@
+# Supabase Project Analyst
+
+Agente especialista em diagnostico read-only de projetos Supabase locais:
+configuracao, migrations, RLS, Auth, Storage, Edge Functions e plano de
+correcao sem executar alteracoes.
+
+## Capabilities
+
+- `inspect-supabase-project`: coleta contexto local e readiness de CLI/MCP.
+- `audit-rls-policies`: audita RLS e policies em SQL local.
+- `audit-auth-security`: audita Auth, claims e exposicao de secrets.
+- `audit-storage-policies`: audita buckets/policies de Storage em SQL local.
+- `review-migrations`: revisa migrations e DDL perigoso.
+- `generate-supabase-report`: consolida findings em relatorio output-only.
+- `plan-supabase-fix`: gera plano e SQL sugerido sem aplicar.
+
+## Uso
+
+```bash
+./agent --json run supabase-project-analyst inspect-supabase-project --project-path .
+```
+
+Este agente nao executa SQL e nao aplica migrations.

package/runtime/agents/supabase-project-analyst/agent.yaml

@@ -0,0 +1,53 @@
+id: supabase-project-analyst
+kind: specialist-agent
+name: Supabase Project Analyst
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Diagnosticar projetos Supabase em modo read-only, analisando configuracao
+  local, migrations, RLS, Auth, Storage, Edge Functions, riscos e planos de
+  correcao sem aplicar mudancas.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional:
+    - SUPABASE_PROJECT_REF
+    - SUPABASE_ACCESS_TOKEN
+    - SUPABASE_DB_URL
+    - SUPABASE_SERVICE_ROLE_KEY
+capabilities:
+  - inspect-supabase-project
+  - audit-rls-policies
+  - audit-auth-security
+  - audit-storage-policies
+  - review-migrations
+  - generate-supabase-report
+  - plan-supabase-fix
+agent_surface:
+  repositories:
+    - infra/integrations/supabase-project/supabase_project_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  inspection: read_only
+  audits: read_only
+  report: output_only
+  fix_plan: dry_run
+  sql_execution: blocked_by_default
+  remote_changes: blocked_by_default
+routing:
+  anchors:
+    - supabase
+    - rls
+    - storage policies
+    - edge functions
+    - supabase auth
+  intents:
+    - supabase.project.audit
+    - supabase.rls.audit
+    - supabase.security.review
+  priority: 50