icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-32-dashboard-ux-medium-impact.md

@@ -0,0 +1,223 @@
+# Phase 32 — Dashboard UX Medium Impact
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 32 |
+| Title | Dashboard UX -- Medium Impact Enhancements |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 10 (Web Dashboard), Phase 30 (Dashboard Authentication & RBAC), Phase 31 (Dashboard UX Low Impact) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+Phase 31 addressed presentation-layer gaps with glossary tooltips, friendly timestamps, breadcrumbs, accessibility, and role-based views. These low-impact changes improved readability and navigation, but the dashboard still lacks interactive capabilities that operators need for daily workflow efficiency.
+
+Compliance posture data exists in the database but is only visible as tabular text. There are no charts showing trends over time, no visual indicators of improvement or regression, and no at-a-glance gauges for readiness scores. Tables cannot be sorted, filtered, or exported, forcing operators to manually scan hundreds of rows. There is no onboarding experience for new users, no real-time updates without manual page refresh, no way to run multi-tool workflows from the UI, and no keyboard shortcuts for power users.
+
+These are "medium impact" changes -- they introduce new client-side JavaScript modules (charts.js, tables.js, tour.js, live.js, batch.js, shortcuts.js) that enhance interactivity without modifying backend APIs or database schemas. Each module is zero-dependency, self-contained, and air-gap safe, following the principle that all modules inject styles via JavaScript (D102) to avoid additional CSS files.
+
+The cumulative effect of Phases 30-32 transforms the dashboard from a static data viewer into an interactive operational console that operators can use as their primary workflow interface.
+
+---
+
+## 2. Goals
+
+1. Implement an SVG chart library (`charts.js`) with zero external dependencies that renders sparkline, line, bar, donut, and gauge chart types from server data, with WCAG-accessible `role="img"` and `aria-label` attributes (D94)
+2. Build table interactivity (`tables.js`) that auto-enhances all `.table-container` tables with search, column sorting, filtering, and CSV export -- no per-table configuration required (D95)
+3. Create a first-visit onboarding tour (`tour.js`) with spotlight overlay, step-by-step guidance, and localStorage-based completion tracking (`icdev_tour_completed`) for air-gap safe detection (D98)
+4. Add SSE-based live updates (`live.js`) with 3-second debounced batches, connection status indicator, and automatic reconnection on failure (D99)
+5. Implement batch operations (`batch.js`) with 4 built-in workflows (ATO Package, Security Scan, Compliance Check, Full Build) runnable from the UI, executing as sequential subprocesses in background threads (D100)
+6. Add keyboard shortcuts (`shortcuts.js`) using a chord pattern (`g` + key) with 1.5-second chord window for navigation, `?` for help modal, and `/` for search focus (D101)
+
+---
+
+## 3. Architecture
+
+```
++---------------------------------------------------------------+
+|                Dashboard UX Layer (Medium Impact)               |
+|                                                                |
+|  +-------------------+    +-----------------------------+      |
+|  | charts.js         |    | tables.js                    |      |
+|  | SVG chart library |    | Auto-enhance all tables      |      |
+|  | 5 chart types     |    | Search, sort, filter, CSV    |      |
+|  | Zero deps, WCAG   |    | No per-table config needed   |      |
+|  +-------------------+    +-----------------------------+      |
+|                                                                |
+|  +-------------------+    +-----------------------------+      |
+|  | tour.js           |    | live.js                      |      |
+|  | Onboarding tour   |    | SSE live updates             |      |
+|  | Spotlight overlay  |    | 3s debounce batching         |      |
+|  | localStorage      |    | Connection status indicator  |      |
+|  | first-visit detect |    | Auto-reconnect on failure    |      |
+|  +-------------------+    +-----------------------------+      |
+|                                                                |
+|  +-------------------+    +-----------------------------+      |
+|  | batch.js          |    | shortcuts.js                 |      |
+|  | Batch operations   |    | Keyboard navigation          |      |
+|  | 4 built-in flows  |    | g+key chord (1.5s window)    |      |
+|  | Background threads |    | ? help, / search             |      |
+|  | Status polling     |    | No browser conflicts         |      |
+|  +-------------------+    +-----------------------------+      |
++---------------------------------------------------------------+
+```
+
+### Chart Types
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| Sparkline | Inline trend indicators | Compliance score trend in table cell |
+| Line | Time-series metrics | Build success rate over 30 days |
+| Bar | Comparative values | STIG findings by category (CAT1/CAT2/CAT3) |
+| Donut | Proportional breakdown | Control satisfaction status |
+| Gauge | Single-value readiness | ATO readiness score (0-100%) |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `g` + `h` | Navigate to Home |
+| `g` + `p` | Navigate to Projects |
+| `g` + `a` | Navigate to Agents |
+| `g` + `m` | Navigate to Monitoring |
+| `g` + `c` | Navigate to Chat |
+| `?` | Show keyboard shortcuts help modal |
+| `/` | Focus search input |
+| `Escape` | Close modal / cancel chord |
+
+---
+
+## 4. Requirements
+
+### 4.1 SVG Chart Library
+
+#### REQ-32-001: Zero-Dependency SVG Charts (D94)
+The system SHALL implement an SVG chart library in `charts.js` with no external dependencies (no Chart.js, no D3.js), rendering charts from server-provided data as lightweight SVG elements.
+
+#### REQ-32-002: Five Chart Types
+The chart library SHALL support sparkline, line, bar, donut, and gauge chart types, each with configurable colors, labels, and dimensions.
+
+#### REQ-32-003: WCAG Accessibility
+All charts SHALL include `role="img"` and `aria-label` attributes with human-readable descriptions of the chart data for screen reader users.
+
+### 4.2 Table Interactivity
+
+#### REQ-32-004: Auto-Enhanced Tables (D95)
+The system SHALL implement table interactivity in `tables.js` that auto-enhances all tables within `.table-container` elements on page load, requiring no per-table configuration.
+
+#### REQ-32-005: Search, Sort, Filter, Export
+Enhanced tables SHALL support full-text search across all columns, click-to-sort on any column header, column value filtering, and one-click CSV export of visible data.
+
+### 4.3 Onboarding Tour
+
+#### REQ-32-006: First-Visit Tour (D98)
+The system SHALL implement an onboarding tour in `tour.js` that activates on first visit, using `localStorage` key `icdev_tour_completed` for detection (no server-side user tracking, air-gap safe).
+
+#### REQ-32-007: Spotlight Overlay
+The tour SHALL use a spotlight overlay that highlights the current step's target element with a semi-transparent backdrop, step counter, and next/previous/skip controls.
+
+### 4.4 Live Updates
+
+#### REQ-32-008: SSE Live Updates (D99)
+The system SHALL implement Server-Sent Events (SSE) based live updates in `live.js`, debouncing to 3-second batches to prevent API hammering while maintaining near-real-time dashboard state.
+
+#### REQ-32-009: Connection Status Indicator
+The live update module SHALL display a visible connection status indicator showing connected (green), reconnecting (yellow), or disconnected (red) state.
+
+### 4.5 Batch Operations
+
+#### REQ-32-010: Four Built-In Workflows (D100)
+The system SHALL implement batch operations in `batch.js` with 4 pre-configured workflows: ATO Package (SSP + POAM + STIG + SBOM), Security Scan (SAST + deps + secrets + container), Compliance Check (multi-framework assessment), and Full Build (scaffold + generate + test + lint).
+
+#### REQ-32-011: Background Execution
+Batch operations SHALL execute as sequential subprocesses in background threads, with the Flask request returning immediately and the frontend polling for status updates.
+
+### 4.6 Keyboard Shortcuts
+
+#### REQ-32-012: Chord Pattern Navigation (D101)
+The system SHALL implement keyboard shortcuts in `shortcuts.js` using a chord pattern (`g` + key) with a 1.5-second chord window, cancelled on invalid key, to avoid conflicts with browser shortcuts.
+
+#### REQ-32-013: Help Modal
+Pressing `?` SHALL display a modal listing all available keyboard shortcuts with their descriptions.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| (No new tables) | Phase 32 is client-side JavaScript only; all data comes from existing APIs |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/dashboard/static/js/charts.js` | Zero-dependency SVG chart library (sparkline, line, bar, donut, gauge) |
+| `tools/dashboard/static/js/tables.js` | Auto-enhancing table interactivity (search, sort, filter, CSV export) |
+| `tools/dashboard/static/js/tour.js` | First-visit onboarding tour with spotlight overlay |
+| `tools/dashboard/static/js/live.js` | SSE live updates with 3-second debounce and connection status |
+| `tools/dashboard/static/js/batch.js` | Batch operations UI with 4 built-in workflows |
+| `tools/dashboard/static/js/shortcuts.js` | Keyboard shortcuts with g+key chord pattern |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D94 | SVG chart library is zero-dependency, renders server data into lightweight SVG | No Chart.js/D3 needed; air-gap safe; WCAG accessible with role="img" and aria-label |
+| D95 | Table interactivity auto-enhances all `.table-container` tables on page load | No per-table configuration; search, sort, filter, CSV export with zero setup |
+| D96 | CLI output formatter uses only Python stdlib (ANSI codes, os.get_terminal_size) | `--human` flag on any tool for colored tables/banners/scores instead of JSON |
+| D98 | Onboarding tour uses localStorage (`icdev_tour_completed`) for first-visit detection | No server-side user tracking; air-gap safe; no additional API endpoints |
+| D99 | SSE live updates debounce to 3-second batches | Prevents API hammering while keeping dashboard near-real-time |
+| D100 | Batch operations run as sequential subprocesses in background threads | Flask request returns immediately; frontend polls status; no blocking |
+| D101 | Keyboard shortcuts use chord pattern (g + key) to avoid conflicts with browser shortcuts | 1.5-second chord window; cancelled on invalid key; familiar pattern from GitHub/GitLab |
+| D102 | All Medium Impact UX modules inject styles via JS (no additional CSS files) | Consistent with ux.js pattern; self-contained modules with no external style dependencies |
+
+---
+
+## 8. Security Gate
+
+**No dedicated security gate for Phase 32.**
+
+Phase 32 is a client-side JavaScript enhancement with no new APIs, no new data exposure, and no database changes. Security is enforced by:
+- Phase 30 authentication and RBAC (all pages require login)
+- Batch operations execute existing tools with existing permissions
+- No client-side JavaScript bypasses server-side access controls
+- CSV export respects role-based visibility (exports only visible data)
+- All SSE connections authenticated via existing session cookies
+
+---
+
+## 9. Commands
+
+```bash
+# Start dashboard (all UX enhancements auto-enabled)
+python tools/dashboard/app.py
+
+# CLI output formatting (any tool that supports --json also supports --human)
+python tools/compliance/stig_checker.py --project-id "proj-123" --human
+python tools/maintenance/maintenance_auditor.py --project-id "proj-123" --human
+
+# Programmatic chart/table usage
+# from tools.cli.output_formatter import format_table, format_banner, format_score
+# print(format_table(["Name", "Status"], [["App1", "healthy"], ["App2", "degraded"]]))
+
+# Dashboard batch operations (via UI at /batch)
+# ATO Package:     SSP + POAM + STIG + SBOM generation
+# Security Scan:   SAST + dependency audit + secret detection + container scan
+# Compliance Check: Multi-framework compliance assessment
+# Full Build:      Scaffold + generate + test + lint
+```
+
+**CUI // SP-CTI**

icdev/data/docs/features/phase-33-modular-installation.md

@@ -0,0 +1,218 @@
+# Phase 33 — Modular Installation
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 33 |
+| Title | Modular Installation |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 21 (SaaS Multi-Tenancy), Phase 23 (Universal Compliance) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV has grown to encompass 15 agents, 15 MCP servers, 20+ compliance frameworks, 6 programming languages, and 183 database tables. Deploying the full system requires significant infrastructure, configuration, and operational expertise. However, not every customer needs every module. An ISV startup building a SaaS product needs a builder, basic security scanning, and a dashboard -- not MBSE integration, supply chain intelligence, or DoD MOSA assessment. A healthcare organization needs HIPAA, HITRUST, and SOC 2 compliance -- not FedRAMP High, CMMC, or CJIS. A DoD program office needs everything including IL6 air-gapped support, but even they may not need the marketplace or innovation engine on day one.
+
+The monolithic deployment model forces customers into an all-or-nothing choice: deploy everything (complex, expensive, more attack surface) or nothing (no value). There is no middle ground. Customers cannot start small and grow, cannot add compliance frameworks as their posture matures, and cannot remove modules they do not need. This creates adoption friction, increases operational cost, and expands the attack surface unnecessarily.
+
+Modular installation solves this by decomposing ICDEV into independently deployable modules with explicit dependency resolution. Customers choose a deployment profile (or build a custom one) that matches their organizational role, compliance posture, target platform, and team size. The installer resolves dependencies, generates platform-specific artifacts (Docker Compose, K8s manifests, Helm values, .env files), and creates only the database tables required by the selected modules. Existing installations can be upgraded incrementally by adding modules or compliance frameworks without disrupting running workloads.
+
+---
+
+## 2. Goals
+
+1. Decompose ICDEV into independently deployable modules with explicit dependency declarations, enabling customers to install only what they need
+2. Provide 10 pre-built deployment profiles (ISV Startup, ISV Enterprise, SI Consulting, SI Enterprise, DoD Team, Healthcare, Financial, Law Enforcement, GovCloud Full, Custom) covering the most common organizational patterns
+3. Implement an interactive wizard that guides new users through platform selection, compliance posture, and module choices with dependency auto-resolution
+4. Generate platform-specific deployment artifacts (Docker Compose, K8s manifests, K8s RBAC, Helm values, .env templates) based on selected modules
+5. Support incremental module addition and upgrade paths for existing installations without disrupting running workloads
+6. Resolve module dependencies automatically: if a module requires another (e.g., marketplace requires SaaS), the installer adds the dependency module
+7. Create only the database tables required by selected modules, reducing schema size and attack surface for minimal installations
+
+---
+
+## 3. Architecture
+
+```
++---------------------------------------------------------------+
+|                    Modular Installer                           |
+|                                                                |
+|  +-------------------+    +-----------------------------+      |
+|  | Interactive       |    | Profile-Based               |      |
+|  | Wizard            |    | Installation                |      |
+|  | --interactive     |    | --profile dod_team          |      |
+|  | 3 questions:      |    | Pre-built bundles:          |      |
+|  |  1. Platform      |    |  ISV Startup (7 modules)    |      |
+|  |  2. Compliance    |    |  DoD Team (14 modules)      |      |
+|  |  3. Modules       |    |  Healthcare (9 modules)     |      |
+|  +--------+----------+    +-----------+-----------------+      |
+|           |                           |                        |
+|           v                           v                        |
+|  +---------------------------------------------------+        |
+|  |           Module Dependency Resolver               |        |
+|  |  installation_manifest.yaml (module definitions)   |        |
+|  |  deployment_profiles.yaml (profile bundles)        |        |
+|  |  Topological sort for install order                |        |
+|  +---------------------------------------------------+        |
+|           |                                                    |
+|           v                                                    |
+|  +---------------------------------------------------+        |
+|  |           Platform Artifact Generator              |        |
+|  |  Docker Compose | K8s Manifests | Helm Values      |        |
+|  |  K8s RBAC | .env Template                          |        |
+|  |  DB table groups (per-module)                      |        |
+|  +---------------------------------------------------+        |
++---------------------------------------------------------------+
+```
+
+### Deployment Profiles
+
+| Profile | Modules | Compliance | Platform | CUI |
+|---------|---------|------------|----------|-----|
+| ISV Startup | 7 core | None | Docker | No |
+| ISV Enterprise | 11 | FedRAMP Moderate | K8s | No |
+| SI Consulting | 5 + RICOAS | FedRAMP + CMMC | Docker | Yes |
+| SI Enterprise | 14 | FedRAMP High + CMMC + CJIS | K8s | Yes |
+| DoD Team | 14 | FedRAMP High + CMMC + FIPS + cATO | K8s | Yes |
+| Healthcare | 9 | HIPAA + HITRUST + SOC 2 | K8s | No |
+| Financial | 9 | PCI DSS + SOC 2 + ISO 27001 | K8s | No |
+| Law Enforcement | 9 | CJIS + FIPS 199/200 | K8s | Yes |
+| GovCloud Full | ALL | ALL | K8s | Yes |
+| Custom | 3 minimum | User choice | User choice | Configurable |
+
+---
+
+## 4. Requirements
+
+### 4.1 Module System
+
+#### REQ-33-001: Module Definitions
+The system SHALL define all ICDEV modules in `args/installation_manifest.yaml`, each with a unique identifier, description, list of dependencies, list of database table groups, list of required configuration files, and list of provided agents/services.
+
+#### REQ-33-002: Dependency Resolution
+The installer SHALL automatically resolve module dependencies using topological sorting, adding required dependency modules when a module is selected.
+
+#### REQ-33-003: Minimum Installation
+The minimum installation SHALL require exactly 3 modules: core (database, memory, audit), builder (scaffolding, code generation, testing), and dashboard (web UI).
+
+#### REQ-33-004: Database Table Groups
+Each module SHALL declare its database table groups so that `init_icdev_db.py` creates only the tables needed by installed modules, reducing schema size for minimal installations.
+
+### 4.2 Installation Modes
+
+#### REQ-33-005: Interactive Wizard
+The system SHALL provide an interactive wizard (`--interactive`) that guides users through 3 setup questions: target platform (Docker/K8s/Helm), compliance frameworks, and module selection with visual dependency tree.
+
+#### REQ-33-006: Profile-Based Installation
+The system SHALL support profile-based installation (`--profile <name>`) using 10 pre-built deployment profiles that bundle modules, compliance frameworks, and platform defaults.
+
+#### REQ-33-007: Compliance Posture Configuration
+The system SHALL support compliance posture selection (`--compliance <frameworks>`) that auto-selects required modules and enables corresponding assessment gates.
+
+### 4.3 Platform Artifacts
+
+#### REQ-33-008: Docker Compose Generation
+The system SHALL generate Docker Compose files containing only the services for selected modules, with appropriate resource limits, network configuration, and volume mounts.
+
+#### REQ-33-009: Kubernetes Manifest Generation
+The system SHALL generate K8s manifests (deployments, services, network policies, RBAC) for selected modules, using the existing STIG-hardened container configurations.
+
+#### REQ-33-010: Helm Values Generation
+The system SHALL generate Helm values files (`values.yaml`) with module-specific overrides for on-premises deployment via the existing Helm chart.
+
+#### REQ-33-011: Environment Template Generation
+The system SHALL generate `.env` template files containing only the environment variables required by selected modules.
+
+### 4.4 Upgrade and Addition
+
+#### REQ-33-012: Module Addition
+The system SHALL support adding modules to an existing installation (`--add-module <name>`) without disrupting running workloads, applying only the incremental database migrations and configuration changes.
+
+#### REQ-33-013: Compliance Addition
+The system SHALL support adding compliance frameworks to an existing installation (`--add-compliance <framework>`) with automatic dependency resolution.
+
+#### REQ-33-014: Upgrade Discovery
+The system SHALL provide an upgrade command (`--upgrade`) that shows which modules can be added to the current installation, including estimated resource impact.
+
+#### REQ-33-015: Installation Status
+The system SHALL provide a status command (`--status`) that reports installed modules, active compliance frameworks, database table count, and configuration completeness.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| (No new tables) | Phase 33 uses the existing `schema_migrations` table (D150) for tracking module installations; module state is derived from installed table groups |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/installer/installer.py` | Main installer entry point: interactive wizard, profile-based, add-module, upgrade, status |
+| `tools/installer/module_registry.py` | Module dependency resolution, validation, table group mapping |
+| `tools/installer/compliance_configurator.py` | Compliance posture selection, framework-to-module mapping, list postures |
+| `tools/installer/platform_setup.py` | Platform artifact generation: Docker Compose, K8s manifests, K8s RBAC, Helm values, .env templates |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D58 | SaaS layer wraps existing tools, does not rewrite them | Module boundaries follow existing tool boundaries; installer activates/deactivates, never rewrites |
+| D60 | Separate database per tenant | Module installation is per-tenant; each tenant can have a different module set |
+| D150 | Lightweight migration runner with `schema_migrations` table | Module additions trigger incremental migrations, not full reinit; checksum validation prevents drift |
+
+---
+
+## 8. Security Gate
+
+**Module Installation Gate:**
+- Dependency resolution must complete without circular dependencies before installation proceeds
+- All selected compliance frameworks must have corresponding assessment tools present in the installation
+- Database migration checksums must validate against expected values before applying incremental changes
+- Platform artifacts must pass validation: Docker Compose `config` check, K8s `kubeval` validation (when available), Helm `lint`
+- Air-gapped installations must have all container images pre-loaded (no registry pull at install time)
+- Module removal is not supported for modules with active audit trail data (append-only preservation)
+
+---
+
+## 9. Commands
+
+```bash
+# Interactive wizard -- guided setup
+python tools/installer/installer.py --interactive
+
+# Profile-based installation
+python tools/installer/installer.py --profile dod_team --compliance fedramp_high,cmmc --platform k8s
+python tools/installer/installer.py --profile isv_startup --platform docker
+python tools/installer/installer.py --profile healthcare --compliance hipaa,hitrust
+
+# Add features to existing installation
+python tools/installer/installer.py --add-module marketplace
+python tools/installer/installer.py --add-compliance hipaa
+python tools/installer/installer.py --upgrade                   # Show what can be added
+
+# Status and validation
+python tools/installer/installer.py --status --json
+python tools/installer/module_registry.py --validate
+python tools/installer/compliance_configurator.py --list-postures
+
+# Platform artifact generation
+python tools/installer/platform_setup.py --generate docker --modules core,llm,builder,dashboard
+python tools/installer/platform_setup.py --generate k8s-rbac --modules core,builder
+python tools/installer/platform_setup.py --generate env --modules core,llm
+python tools/installer/platform_setup.py --generate helm-values --modules core,llm,builder
+```
+
+**CUI // SP-CTI**