commit a4b224da8ebb48da08e5a48ca8651f540c1fe781 Author: valenti Date: Tue Sep 8 07:21:34 2026 -0400 first diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..d340979 --- /dev/null +++ b/.env.example @@ -0,0 +1,102 @@ +# ============================================================ +# ASF - Environment Configuration (SAFE DEFAULTS ONLY) +# Copy this file to .env and replace placeholders with real values. +# NEVER commit .env with real secrets to version control. +# ============================================================ + +# ------------------------------------------------------------ +# General +# ------------------------------------------------------------ +ASF_ENV=development +ASF_LOG_LEVEL=INFO +ASF_CORS_ORIGINS=http://localhost:3000,http://localhost:8080 + +# ------------------------------------------------------------ +# MongoDB (Replica Set rs0 — seed nodes 102/103) +# ------------------------------------------------------------ +MONGO_HOST=172.19.40.102,172.19.40.103 +MONGO_PORT=27017 +MONGO_DB=asf +MONGO_REPLICA_SET=rs0 +# Connection URI: seed list + replicaSet=rs0 (add credentials when/if required) +MONGO_URI=mongodb://172.19.40.102:27017,172.19.40.103:27017/asf?replicaSet=rs0 + +# ------------------------------------------------------------ +# RabbitMQ (node 201 / vhost asf) +# ------------------------------------------------------------ +RABBITMQ_HOST=172.19.40.201 +RABBITMQ_PORT=5672 +RABBITMQ_HTTP_PORT=15672 +RABBITMQ_USER=azurian +RABBITMQ_PASSWORD=StrongPassword123! +RABBITMQ_VHOST=asf +RABBITMQ_URI=amqp://azurian:StrongPassword123!@172.19.40.201:5672/asf + +# ------------------------------------------------------------ +# Redis +# ------------------------------------------------------------ +REDIS_HOST=localhost +REDIS_PORT=6379 +REDIS_PASSWORD=asfredis123 +REDIS_URI=redis://:asfredis123@localhost:6379/0 + +# ------------------------------------------------------------ +# MinIO / S3-compatible storage +# ------------------------------------------------------------ +MINIO_HOST=localhost +MINIO_PORT=9000 +MINIO_CONSOLE_PORT=9001 +MINIO_ROOT_USER=asfadmin +MINIO_ROOT_PASSWORD=asfadmin123 +MINIO_BUCKET=asf-artifacts +MINIO_SECURE=false + +# ------------------------------------------------------------ +# ASF AI Gateway (Mock / Provider configuration) +# ------------------------------------------------------------ +AI_GATEWAY_PROVIDER=mock +AI_GATEWAY_DEFAULT_MODEL=asf-mock-v1 +AI_GATEWAY_TIMEOUT=120 + +# Real provider configuration (fill only when enabling): +# OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +# OPENAI_BASE_URL=https://api.openai.com/v1 +# NVIDIA_API_KEY=nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +# ------------------------------------------------------------ +# Security / Auth (bootstrap placeholders) +# ------------------------------------------------------------ +ASF_JWT_SECRET=replace-this-with-a-long-random-secret-in-production +ASF_API_KEY_SALT=replace-this-with-a-long-random-salt-in-production +ASF_SESSION_TTL_SECONDS=86400 + +# ------------------------------------------------------------ +# Frontend (Next.js asf-web) +# ------------------------------------------------------------ +# Where Next.js rewrites should proxy `/api/v1/*` (asf-core URL) +NEXT_PUBLIC_ASF_CORE_URL=http://localhost:8000 +# Bootstrap dev-trust: browser-side defaults for X-ASF-Tenant-Id / X-ASF-User-Id +NEXT_PUBLIC_DEV_TENANT_ID=t-demo-001 +NEXT_PUBLIC_DEV_USER_ID=u-admin + +# ------------------------------------------------------------ +# RabbitMQ exchanges + queue topology (matches rabbitmq.py bindings) +# ------------------------------------------------------------ +RABBITMQ_EVENTS_EXCHANGE=asf.events +RABBITMQ_JOBS_EXCHANGE=asf.jobs + +# Domain topic queues bound to `asf.events` (TOPIC) +RABBITMQ_QUEUE_ORG_CREATED=asf.organization.created +RABBITMQ_QUEUE_PROJ_CREATED=asf.project.created +RABBITMQ_QUEUE_PROJ_UPDATED=asf.project.updated +RABBITMQ_QUEUE_ART_CREATED=asf.artifact.created +RABBITMQ_QUEUE_ART_UPDATED=asf.artifact.updated +RABBITMQ_QUEUE_AUDIT=asf.audit +RABBITMQ_QUEUE_AI_EXEC=asf.ai.execution +RABBITMQ_QUEUE_DEADLETTER=asf.deadletter + +# Job direct queues bound to `asf.jobs` (DIRECT) — consumed by asf-worker +ASF_WORKER_JOB_QUEUES=asf.ai.interactive,asf.ai.background,asf.indexing,asf.code_analysis,asf.testing,asf.devops,asf.notifications +ASF_WORKER_ID=asf-worker-001 +ASF_WORKER_PREFETCH=8 +ASF_WORKER_ENABLE_AI_HANDLERS=true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a91434b --- /dev/null +++ b/.gitignore @@ -0,0 +1,106 @@ +# ============================================================ +# Python +# ============================================================ +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +pip-wheel-metadata/ + +# Virtual environments +.venv/ +venv/ +env/ +ENV/ + +# ============================================================ +# Node / Next.js / Frontend +# ============================================================ +node_modules/ +.next/ +out/ +dist/ +.DS_Store +*.pem +.npm + +# Build output +frontend/asf-web/.next/ +frontend/asf-web/out/ +frontend/asf-web/node_modules/ + +# ============================================================ +# Environment & Secrets +# ============================================================ +.env +.env.* +!.env.example +*.local + +# ============================================================ +# IDE +# ============================================================ +.idea/ +.vscode/ +*.swp +*.swo +*~ +.project +.classpath + +# ============================================================ +# Testing & Coverage +# ============================================================ +.pytest_cache/ +.coverage +htmlcov/ +.tox/ +.mypy_cache/ +.ruff_cache/ +coverage/ +*.lcov + +# ============================================================ +# Logs +# ============================================================ +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# ============================================================ +# Docker +# ============================================================ +docker-compose.override.yml + +# ============================================================ +# Data volumes (we use named volumes in compose, but just in case) +# ============================================================ +data/ +*.sqlite +*.db + +# ============================================================ +# OS +# ============================================================ +Thumbs.db +ehthumbs.db +Desktop.ini +$RECYCLE.BIN/ diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..4d40e4a --- /dev/null +++ b/AGENT.md @@ -0,0 +1,649 @@ +# AGENT.md + +# Azurian Software Factory - AI Engineering Rules + +This file defines mandatory rules for AI coding agents working on the Azurian Software Factory repository. + +Read this document before modifying code. + +--- + +## 1. Product Identity + +Product: + +**Azurian Software Factory (ASF)** + +Tagline: + +> From Requirement to Production, everything is contextualized, traceable and AI-accessible. + +ASF is an AI-native, multi-tenant Software Factory SaaS. + +ASF connects the complete software lifecycle: + +Requirement → Architecture → Task → Code → Commit → Pull Request → Build → Test → Deployment → Runtime → Incident → Feedback. + +ASF is not merely an AI coding assistant. + +--- + +## 2. Core Principle + +The central ASF principle is: + +> Everything is an Artifact. + +Requirements, architecture decisions, documents, source code references, commits, tests, builds, deployments, incidents and AI analyses can all be represented as Artifacts. + +Artifacts may have relationships with other Artifacts. + +Never implement functionality that unnecessarily breaks this generic model. + +--- + +## 3. Architectural Principles + +All implementations must preserve: + +1. Multi-tenancy +2. Traceability +3. Context preservation +4. API-first design +5. Event-driven architecture +6. AI provider independence +7. Integration provider independence +8. Horizontal scalability +9. Auditability +10. Security by design + +--- + +## 4. Technology Baseline + +### Backend + +Use: + +- Python 3.12+ +- FastAPI +- Pydantic +- async/await +- MongoDB +- RabbitMQ +- Redis +- MinIO/S3 + +Do not introduce another primary database without an ADR. + +### Frontend + +Use: + +- Next.js +- React +- TypeScript +- Tailwind CSS +- shadcn/ui +- TanStack Query +- React Flow + +Use Zustand only where persistent/shared client state is genuinely necessary. + +### AI + +All model access must go through the ASF AI Gateway abstraction. + +Never call a specific LLM provider directly from domain/business code. + +### Messaging + +RabbitMQ is the primary event and asynchronous messaging backbone. + +MongoDB is the persistent source of truth for job state. + +--- + +## 5. Multi-Tenancy + +Every tenant-owned entity must contain `tenant_id`. + +Where appropriate it must also contain `project_id`. + +Never trust tenant identity supplied directly by a browser request. + +Tenant context must come from validated authentication/authorization context. + +Every database query involving tenant-owned data must be tenant scoped. + +Cross-tenant data leakage is considered a critical defect. + +Tests must cover tenant isolation for sensitive operations. + +--- + +## 6. Artifact Rules + +Prefer the generic Artifact model for lifecycle entities. + +Artifact types may include: + +- requirement +- epic +- story +- task +- architecture_decision +- document +- source_file +- commit +- pull_request +- build +- test +- deployment +- release +- security_finding +- runtime_event +- incident +- ai_analysis + +Do not create a new MongoDB collection for every artifact type unless there is a documented architectural reason. + +Artifact metadata must remain extensible. + +--- + +## 7. Relationships + +Artifact relationships must be explicit and queryable. + +Examples: + +- implements +- implemented_by +- verifies +- verified_by +- generated_from +- documented_by +- depends_on +- affects +- deployed_as +- caused_by +- supersedes +- related_to + +Do not encode important traceability relationships only inside free text. + +--- + +## 8. Context + +AI operations must receive relevant context through the ASF Context Engine. + +Do not build arbitrary RAG logic directly inside API endpoints or UI code. + +Context retrieval must remain independently evolvable. + +The architecture must allow future integration of: + +- embeddings +- vector search +- graph traversal +- source code indexing +- document indexing +- runtime telemetry + +--- + +## 9. AI Rules + +ASF must remain model agnostic. + +Supported architectures may include: + +- DGX-hosted models +- OpenAI-compatible APIs +- external providers +- future customer-hosted models + +Model selection belongs to the AI Gateway. + +Business services request capabilities, not specific model implementations. + +Prefer concepts such as: + +`analyze_code()` + +over: + +`call_qwen()` + +unless inside a provider adapter. + +Record AI usage when technically available. + +Never expose model credentials to frontend code. + +--- + +## 10. Queue Rules + +Separate interactive and background workloads. + +Typical queues: + +- asf.ai.interactive +- asf.ai.background +- asf.indexing +- asf.code_analysis +- asf.testing +- asf.devops +- asf.notifications + +Interactive user requests should receive higher scheduling priority than non-critical background work. + +Workers must be stateless where practical and horizontally scalable. + +Do not rely on process memory for persistent job state. + +Consumers must be designed for duplicate delivery. + +Where side effects occur, use idempotency mechanisms. + +Do not assume exactly-once delivery. + +--- + +## 11. Event Rules + +Events describe facts that happened. + +Prefer: + +`artifact.created` + +`requirement.updated` + +`deployment.completed` + +instead of ambiguous event names. + +Every distributed event should contain sufficient metadata for tracing, including where applicable: + +- event_id +- event_type +- timestamp +- tenant_id +- project_id +- correlation_id +- causation_id +- payload + +Do not place large binary content directly in RabbitMQ messages. + +Store large content in MinIO and transmit a reference. + +--- + +## 12. MinIO Rules + +Use MinIO/S3 for: + +- uploaded documents +- generated files +- large reports +- repository archives where appropriate +- large AI inputs/outputs where persistence is required + +MongoDB should store metadata and object references. + +Do not store large binary objects directly in normal MongoDB documents unless specifically justified. + +--- + +## 13. API Rules + +REST API prefix: + +`/api/v1` + +Health endpoint: + +`GET /api/v1/health` + +Use: + +- Pydantic request/response models +- explicit validation +- consistent HTTP status codes +- consistent error responses + +Do not expose MongoDB internal structures directly through APIs. + +Do not put business logic directly inside FastAPI route functions. + +Routes should delegate to application/domain services. + +--- + +## 14. Python Rules + +Use type hints. + +Prefer async I/O for: + +- MongoDB +- RabbitMQ +- Redis +- HTTP +- MinIO operations where supported + +Keep functions focused. + +Avoid giant service classes. + +Avoid hidden global state. + +Use dependency injection where it improves testing and separation. + +Do not catch `Exception` unless there is a deliberate boundary-level reason. + +Never silently ignore errors. + +--- + +## 15. Frontend Rules + +Frontend components must not contain backend business rules. + +Never access MongoDB, RabbitMQ, Redis or MinIO directly from the browser. + +Use the ASF API. + +Pages must support: + +- loading state +- empty state +- error state + +Do not present mocked data as production data. + +Traceability visualization must use reusable node/edge components. + +The UI must remain responsive and accessible. + +--- + +## 16. Security Rules + +Never commit: + +- passwords +- API keys +- private keys +- tokens +- certificates +- production credentials + +Use environment configuration. + +Provide `.env.example` containing names and safe placeholder values only. + +Never log authentication secrets. + +Validate uploaded files. + +Validate external connector input. + +Assume external webhook payloads are untrusted. + +--- + +## 17. Logging and Observability + +Use structured JSON logging on backend services. + +Propagate where applicable: + +- correlation_id +- tenant_id +- project_id +- job_id + +Prepare services for OpenTelemetry instrumentation. + +Logs are operational telemetry. + +Audit events are business/security records. + +Do not confuse the two concepts. + +--- + +## 18. Connectors + +External systems must be isolated behind connector interfaces. + +Examples: + +- GitHub +- GitLab +- Bitbucket +- Jira +- Confluence +- Notion +- Jenkins +- SonarQube +- Grafana + +Do not spread provider-specific APIs throughout ASF business code. + +MCP should be preferred where it provides a suitable standardized capability. + +REST and Webhooks remain supported integration mechanisms. + +--- + +## 19. Testing Rules + +Backend tests use pytest. + +Tests should cover: + +- domain logic +- API behavior +- artifact relationships +- job state transitions +- event handling +- tenant isolation + +Bug fixes should include regression tests where practical. + +Do not remove failing tests merely to make the build green. + +--- + +## 20. Database Rules + +MongoDB is the primary ASF datastore. + +Collections and indexes must be intentionally designed. + +Common queries must have appropriate indexes. + +Tenant-aware compound indexes should be considered. + +Schema flexibility does not mean schema absence. + +Pydantic models define application-level contracts. + +Database migrations or data transformation scripts must be versioned. + +--- + +## 21. Architectural Decisions + +Significant architectural decisions require an ADR under: + +`docs/adr/` + +Examples: + +- introducing a new database +- introducing a new message broker +- changing tenancy strategy +- changing authentication architecture +- introducing a graph database +- changing artifact representation +- replacing the AI Gateway +- changing event semantics + +Do not make major architectural changes silently. + +--- + +## 22. Code Changes + +Before modifying code: + +1. Understand the requested change. +2. Inspect relevant existing code. +3. Identify affected modules. +4. Check existing tests. +5. Preserve architectural boundaries. + +After modifying code: + +1. Run relevant tests. +2. Run lint/type checks where configured. +3. Fix failures introduced by the change. +4. Review tenant isolation. +5. Review error handling. +6. Update documentation when behavior or architecture changed. + +--- + +## 23. Dependency Policy + +Do not add dependencies unnecessarily. + +Before introducing a library, determine whether: + +- the standard library already solves the problem +- an existing project dependency solves it +- the new dependency is actively maintained +- it introduces security or licensing concerns + +Major framework additions require justification. + +--- + +## 24. Simplicity + +Do not over-engineer ASF. + +Prefer: + +simple → testable → observable → scalable + +over: + +complex → theoretical → difficult to operate. + +Microservices are not a goal. + +Service boundaries must exist because they provide operational or domain value. + +--- + +## 25. Current Logical Components + +The initial architecture consists of: + +`asf-core` + +Core API, organizations, projects, artifacts, relationships, jobs and audit. + +`asf-context` + +Context assembly, relationship traversal and future semantic retrieval. + +`asf-ai` + +AI Gateway, provider abstraction, routing and usage. + +`asf-worker` + +RabbitMQ consumers and asynchronous processing. + +`asf-web` + +Next.js SaaS frontend. + +Do not create additional services unless there is a clear reason. + +--- + +## 26. Source of Truth + +MongoDB: +structured application/domain state. + +MinIO: +large files and binary artifacts. + +RabbitMQ: +events and work delivery. + +Redis: +temporary/cache/coordination state. + +AI models: +never considered authoritative sources of ASF business data. + +--- + +## 27. AI Generated Changes + +AI-generated code is subject to exactly the same engineering standards as human-written code. + +Never assume generated code is correct. + +Validate: + +- imports +- APIs +- library versions +- async behavior +- security +- tenancy +- error handling +- tests + +Never invent an API from an external dependency when its actual interface can be inspected. + +--- + +## 28. Definition of Done + +A change is not complete merely because code was generated. + +A change is complete when: + +- implementation works +- relevant tests pass +- tenant isolation is preserved +- errors are handled +- observability is maintained +- architecture rules are respected +- documentation is updated where necessary +- no credentials or sensitive data were introduced + +--- + +## 29. Guiding Question + +When implementing any ASF feature, ask: + +> Does this improve the connection between software context, traceability, automation and AI? + +If the feature bypasses those principles, reconsider the implementation. \ No newline at end of file diff --git a/HISTORY-CHANGES.md b/HISTORY-CHANGES.md new file mode 100644 index 0000000..1812ad1 --- /dev/null +++ b/HISTORY-CHANGES.md @@ -0,0 +1,178 @@ +# ASF (Azurian Software Factory) — History dei Cambiamenti + +> Formato: **YYYY-MM-DD · Gruppo Release · Sezioni Added / Changed / Fixed / Tests / Docs / Infra** +> Ultimo aggiornamento: `2026-09-08` · Data oggi del sistema: `2026-09-08` + +--- + +## 📦 Release 2026-09-08 (Sessione odierna — Principale) +*Obiettivo: completare la copertura 100% CRUD UI + test 40/40 + Tutorial UI click-only + Context Explorer.* + +--- + +### ✅ Added — Frontend (5 nuove feature UI completate oggi) + +| Ref | Funzionalità | File & Riferimento | +|---|---|---| +| A1 | **Settings Page REALE (2 modali create org + create proj)** | [settings/page.tsx:1-533](file:///root/ASF/frontend/asf-web/app/settings/page.tsx#L1-L533) | +| A1.1 | Modale **New Organization** — 7 campi: name, slug (regex `[a-z0-9-]{3,60}` hint live), plan (Free/Team/Business/Enterprise), toggle Active · `POST /organizations` | [settings/page.tsx:348-408](file:///root/ASF/frontend/asf-web/app/settings/page.tsx#L348-L408) | +| A1.2 | Modale **New Project** — 6 campi: name, key (regex `^[A-Z][A-Z0-9]{1,19}$` hint live uppercase), default_branch, description, active · `POST /projects` | [settings/page.tsx:411-478](file:///root/ASF/frontend/asf-web/app/settings/page.tsx#L411-L478) | +| A1.3 | 2 Tabelle Organizations & Projects (5 colonne ciascuna) + sidebar Profile sec="org" di default + componenti Field/Toggle helper | [settings/page.tsx:200-293](file:///root/ASF/frontend/asf-web/app/settings/page.tsx#L200-L293) · [Field/Toggle 483-533](file:///root/ASF/frontend/asf-web/app/settings/page.tsx#L483-L533) | +| A2 | **Requirements — "New Requirement" PULSANTE FUNZIONANTE** · Prima ` + )} + + + + +
+

Try asking

+
+ {suggestions.map((s) => ( + + ))} +
+
+ + + + + +
+ + + Conversation + {pendingJob && ( + ) ?? "running"]} className="animate-pulse"> + + Processing… + + )} + +
+
+ +
+
+ +
+ {messages.length === 0 ? ( +
+ +
+ ) : ( + messages.map((m) => ( + handleCopy(m.id, m.content)} + copied={copied === m.id} + onJumpArtifact={(id) => { + const u = `/context?artifact=${encodeURIComponent(id)}`; + window.open(u, "_blank", "noopener"); + }} + /> + )) + )} +
+ +
+
+
+