agent-devkit 0.1.5 → 0.2.0

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

@@ -52,6 +52,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
+    - database
+    - migracao
+    - migration
+    - postgres
+  intents:
+    - database.change
+  priority: 35

package/runtime/agents/docker-container-builder/AGENTS.md

@@ -0,0 +1,27 @@
+# Docker Container Builder
+
+Instrucoes locais para trabalhar no agente `docker-container-builder`.
+
+## Responsabilidade
+
+Este agente planeja, gera e revisa artefatos Docker locais, incluindo
+`Dockerfile`, `.dockerignore`, `docker-compose.yml` e `README.docker.md`.
+O objetivo e containerizar projetos de forma revisavel, segura e portavel sem
+executar build, push ou deploy real.
+
+## Fora De Escopo
+
+- Executar `docker build`, `docker compose up`, `docker push` ou deploy real.
+- Criar infraestrutura cloud, Kubernetes, Helm ou registry remoto.
+- Persistir segredos em imagens, compose ou logs.
+- Fazer supply-chain hardening avancado fora do checklist inicial.
+
+## Guardrails
+
+- Gerar `.dockerignore` sempre que gerar `Dockerfile`.
+- Nao copiar `.env`, `.ssh`, chaves, caches, `.git`, `node_modules` ou `.venv`.
+- Preferir usuario nao-root.
+- Evitar `latest` em alvo `prod`.
+- Nao gerar `privileged`, `network_mode: host` ou bind mount de `/`.
+- Build, push e deploy devem aparecer apenas como plano dry-run.
+- Escrita local deve ficar restrita a `target_project`.

package/runtime/agents/docker-container-builder/README.md

@@ -0,0 +1,21 @@
+# Docker Container Builder
+
+Agente especialista em gerar e revisar artefatos Docker locais.
+
+## Capabilities
+
+- `analyze-containerization-target`: inspeciona projeto local e detecta sinais
+  de linguagem, entrypoint, portas e riscos.
+- `generate-dockerfile`: gera conteudo de `Dockerfile` em modo output-only.
+- `generate-compose`: gera `docker-compose.yml` para desenvolvimento local em
+  modo output-only.
+- `generate-container-project-files`: planeja ou escreve arquivos Docker locais
+  com `--execute`.
+- `review-docker-security`: revisa Dockerfile/compose existentes ou texto.
+- `plan-image-build`: gera comandos de build/tag/run sem executar Docker.
+
+## Politica
+
+O agente nao executa Docker CLI. Build, push e deploy reais permanecem
+bloqueados por padrao e devem ser tratados por capabilities futuras com policy
+propria.

package/runtime/agents/docker-container-builder/agent.yaml

@@ -0,0 +1,52 @@
+id: docker-container-builder
+kind: specialist-agent
+name: Docker Container Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Planejar, gerar e revisar artefatos Docker locais seguros e revisaveis,
+  incluindo Dockerfile, .dockerignore, docker-compose.yml, README.docker.md e
+  planos de build sem executar build, push ou deploy real.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - analyze-containerization-target
+  - generate-dockerfile
+  - generate-compose
+  - generate-container-project-files
+  - review-docker-security
+  - plan-image-build
+agent_surface:
+  repositories:
+    - infra/integrations/docker-container/docker_container_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  analysis: read_only
+  dockerfile_generation: output_only
+  compose_generation: output_only
+  project_files: local_write
+  review: read_only
+  build_plan: dry_run
+  build_real: blocked_by_default
+  push_real: blocked_by_default
+  deploy_real: blocked_by_default
+routing:
+  anchors:
+    - docker-container-builder
+    - docker
+    - dockerfile
+    - docker-compose
+    - container
+    - containerization
+  intents:
+    - docker.generate
+    - docker.review
+    - docker.containerize
+  priority: 50

package/runtime/agents/docker-container-builder/capabilities/analyze-containerization-target/capability.yaml

@@ -0,0 +1,18 @@
+id: docker-container-builder.analyze-containerization-target
+kind: capability
+name: Analyze Containerization Target
+version: 0.1.0
+status: draft
+purpose: Analisar projeto local para planejar containerizacao Docker sem escrever arquivos.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/container-plan.md
+inputs:
+  required:
+    - project-path
+  optional: []
+outputs:
+  artifacts:
+    - containerization-analysis.json
+write_policy: read_only

package/runtime/agents/docker-container-builder/capabilities/analyze-containerization-target/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao executar comandos do projeto.
+- Nao ler arquivos grandes acima do limite do repository.
+- Reportar segredos apenas por marcador, nunca por valor.
+- Se a linguagem for ambigua, retornar `unknown` e perguntas abertas.

package/runtime/agents/docker-container-builder/capabilities/analyze-containerization-target/runner.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Runner for docker-container-builder/analyze-containerization-target."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "docker-container"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from docker_container_repository import DockerContainerBuilderError, DockerContainerRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Analyze a local project for Docker containerization")
+    parser.add_argument("--project-path", required=True)
+    args = parser.parse_args()
+    try:
+        result = DockerContainerRepository().analyze_containerization_target(project_path=Path(args.project_path))
+    except DockerContainerBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/docker-container-builder/capabilities/analyze-containerization-target/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Receber `project-path`.
+2. Inspecionar arquivos manifestos e sinais de runtime.
+3. Detectar linguagem, package manager, entrypoint provavel, portas e riscos.
+4. Retornar fatos, lacunas e proximos passos sem escrever arquivos.

package/runtime/agents/docker-container-builder/capabilities/generate-compose/capability.yaml

@@ -0,0 +1,18 @@
+id: docker-container-builder.generate-compose
+kind: capability
+name: Generate Compose
+version: 0.1.0
+status: draft
+purpose: Gerar docker-compose.yml para desenvolvimento local em modo output-only.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/docker-compose.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - docker-compose.yml
+write_policy: output_only

package/runtime/agents/docker-container-builder/capabilities/generate-compose/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Compose e para desenvolvimento local por padrao.
+- Nao gerar `privileged`.
+- Nao gerar `network_mode: host`.
+- Nao montar `/` ou diretorios sensiveis do host.
+- Variaveis devem ser referencias, nao valores secretos.

package/runtime/agents/docker-container-builder/capabilities/generate-compose/runner.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Runner for docker-container-builder/generate-compose."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "docker-container"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from docker_container_repository import DockerContainerBuilderError, DockerContainerRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate docker-compose.yml without writing files")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+    try:
+        result = DockerContainerRepository().generate_compose(spec_path=Path(args.spec))
+    except DockerContainerBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/docker-container-builder/capabilities/generate-compose/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar portas, variaveis e services.
+3. Gerar compose local sem secrets embutidos.
+4. Retornar conteudo sem escrever no disco.

package/runtime/agents/docker-container-builder/capabilities/generate-container-project-files/capability.yaml

@@ -0,0 +1,20 @@
+id: docker-container-builder.generate-container-project-files
+kind: capability
+name: Generate Container Project Files
+version: 0.1.0
+status: draft
+purpose: Planejar ou escrever artefatos Docker locais dentro de target_project.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/container-plan.md
+inputs:
+  required:
+    - spec
+  optional:
+    - execute
+    - allow-overwrite
+outputs:
+  artifacts:
+    - container-project-files.json
+write_policy: local_write

package/runtime/agents/docker-container-builder/capabilities/generate-container-project-files/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Escrita real requer `--execute`.
+- Sobrescrita requer `--allow-overwrite`.
+- Bloquear paths absolutos e path traversal.
+- Sempre incluir `.dockerignore` se houver `Dockerfile`.
+- Nao executar Docker CLI.

package/runtime/agents/docker-container-builder/capabilities/generate-container-project-files/runner.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Runner for docker-container-builder/generate-container-project-files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "docker-container"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from docker_container_repository import DockerContainerBuilderError, DockerContainerRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate Docker project files")
+    parser.add_argument("--spec", required=True)
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--allow-overwrite", action="store_true")
+    args = parser.parse_args()
+    try:
+        result = DockerContainerRepository().generate_container_project_files(
+            spec_path=Path(args.spec),
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except DockerContainerBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/docker-container-builder/capabilities/generate-container-project-files/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar `target_project`.
+3. Planejar arquivos Docker e bloqueios de seguranca.
+4. Sem `--execute`, retornar lista de arquivos planejados.
+5. Com `--execute`, escrever apenas dentro de `target_project`.

package/runtime/agents/docker-container-builder/capabilities/generate-dockerfile/capability.yaml

@@ -0,0 +1,18 @@
+id: docker-container-builder.generate-dockerfile
+kind: capability
+name: Generate Dockerfile
+version: 0.1.0
+status: draft
+purpose: Gerar conteudo de Dockerfile seguro em modo output-only.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/dockerfile.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - Dockerfile
+write_policy: output_only

package/runtime/agents/docker-container-builder/capabilities/generate-dockerfile/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Sempre preferir usuario nao-root.
+- Nao usar `latest` para target `prod`.
+- Incluir healthcheck quando houver porta HTTP.
+- Nao executar build.

package/runtime/agents/docker-container-builder/capabilities/generate-dockerfile/runner.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Runner for docker-container-builder/generate-dockerfile."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "docker-container"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from docker_container_repository import DockerContainerBuilderError, DockerContainerRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a Dockerfile without writing files")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+    try:
+        result = DockerContainerRepository().generate_dockerfile(spec_path=Path(args.spec))
+    except DockerContainerBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/docker-container-builder/capabilities/generate-dockerfile/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar linguagem, target e entrypoint.
+3. Bloquear marcadores de segredo hardcoded.
+4. Gerar Dockerfile sem escrever no disco.
+5. Retornar conteudo e findings de seguranca.

package/runtime/agents/docker-container-builder/capabilities/plan-image-build/capability.yaml

@@ -0,0 +1,18 @@
+id: docker-container-builder.plan-image-build
+kind: capability
+name: Plan Image Build
+version: 0.1.0
+status: draft
+purpose: Gerar plano de build, tags e comandos Docker sem executar build/push.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/container-plan.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - image-build-plan.json
+write_policy: dry_run

package/runtime/agents/docker-container-builder/capabilities/plan-image-build/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nunca executar `docker build`, `docker run`, `docker compose` ou `docker push`.
+- `push` real e bloqueado por padrao.
+- Tags devem ser explicitas; evitar `latest` em producao.
+- Comandos sao instrucoes para revisao humana.

package/runtime/agents/docker-container-builder/capabilities/plan-image-build/runner.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Runner for docker-container-builder/plan-image-build."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "docker-container"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from docker_container_repository import DockerContainerBuilderError, DockerContainerRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan Docker image build commands without execution")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+    try:
+        result = DockerContainerRepository().plan_image_build(spec_path=Path(args.spec))
+    except DockerContainerBuilderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/docker-container-builder/capabilities/plan-image-build/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar nome da imagem, target e tags.
+3. Gerar comandos de build/run/push apenas para revisao.
+4. Marcar build/push/deploy real como bloqueados.

package/runtime/agents/docker-container-builder/capabilities/review-docker-security/capability.yaml

@@ -0,0 +1,21 @@
+id: docker-container-builder.review-docker-security
+kind: capability
+name: Review Docker Security
+version: 0.1.0
+status: draft
+purpose: Revisar Dockerfile e compose contra guardrails de seguranca.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/container-review.md
+inputs:
+  required: []
+  optional:
+    - dockerfile
+    - compose
+    - dockerfile-text
+    - compose-text
+outputs:
+  artifacts:
+    - docker-security-review.json
+write_policy: read_only

package/runtime/agents/docker-container-builder/capabilities/review-docker-security/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao executar Docker CLI.
+- Nao imprimir valores de segredos.
+- Findings devem ter severidade, codigo, risco e recomendacao.
+- Ausencia de Dockerfile e finding bloqueante quando nenhum texto foi informado.

package/runtime/agents/docker-container-builder/capabilities/review-docker-security/runner.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Runner for docker-container-builder/review-docker-security."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "docker-container"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from docker_container_repository import DockerContainerBuilderError, DockerContainerRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Review Docker artifacts")
+    parser.add_argument("--dockerfile")
+    parser.add_argument("--compose")
+    parser.add_argument("--dockerfile-text")
+    parser.add_argument("--compose-text")
+    args = parser.parse_args()
+    if not any((args.dockerfile, args.compose, args.dockerfile_text, args.compose_text)):
+        print("one of --dockerfile, --compose, --dockerfile-text or --compose-text is required", file=sys.stderr)
+        return 2
+    try:
+        result = DockerContainerRepository().review_docker_security(
+            dockerfile_path=Path(args.dockerfile) if args.dockerfile else None,
+            compose_path=Path(args.compose) if args.compose else None,
+            dockerfile_text=args.dockerfile_text,
+            compose_text=args.compose_text,
+        )
+    except (DockerContainerBuilderError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/docker-container-builder/capabilities/review-docker-security/workflow.md

@@ -0,0 +1,5 @@
+# Workflow
+
+1. Receber caminho ou texto de Dockerfile/compose.
+2. Revisar root, secrets, imagem base, latest, copy amplo, ports, privileged e host network.
+3. Retornar findings com severidade e recomendacao.