.

Toolbox/docs/documentation/sdlc/PROMPT-v2.md

@@ -0,0 +1,392 @@
+AUTONOMOUS EXECUTION PROMPT FOR QWEN3-CODER
+
+MISSION: Generate a production-grade Docker image for document generation that builds ON FIRST ATTEMPT with OPTIMAL CACHING and MULTI-ARCHITECTURE SUPPORT. NO ITERATION ALLOWED - OUTPUT MUST BE PERFECT.
+
+CRITICAL PERFORMANCE CONSTRAINTS:
+
+BUILD TIME OPTIMIZATION IS PARAMOUNT - You MUST implement advanced BuildKit caching strategies including:
+Multi-stage builds with proper layer isolation 
+Dependency installation BEFORE application code to maximize cache hits 
+Use --mount=type=cache directives for mise/npm/pip/cargo caches
+Separate apt-get operations into dedicated cacheable layers 
+Implement cache mounts for ~/.cache/mise and ~/.local/share/mise
+BUILDKIT CONFIGURATION: Every Dockerfile instruction MUST leverage BuildKit features:
+dockerfile
+
+
+1
+2
+# syntax=docker/dockerfile:1.4
+# Enable ALL BuildKit optimizations
+Use RUN --mount=type=cache for ALL tool installations
+Implement --cache-from and --cache-to in build.sh
+Enable parallel downloading with --parallel flag where applicable
+MULTI-ARCHITECTURE BUILD:
+Use docker buildx with --platform linux/amd64,linux/arm64,linux/arm/v7
+Implement proper QEMU emulation setup in build.sh
+Use manifest lists for final image deployment
+SECURITY & ARCHITECTURE REQUIREMENTS:
+
+STAGE 1 (BUILDER): Root only for minimal apt operations and user creation
+STAGE 2 (RUNTIME): 100% tsysdevstack user, NO ROOT CAPABILITIES
+LAYER ORDERING PRINCIPLE: Place infrequently changing operations at top:
+Base image + system packages (pinned versions)
+mise installation + runtime versions (pinned)
+Global tool installations (pinned versions)
+Application code/configurations
+CACHE BUSTING PREVENTION: Version pin EVERYTHING - no "latest" tags 
+QA GATES - NON-NEGOTIABLE:
+
+PRE-BUILD VALIDATION: Generate build.sh to run these checks BEFORE any docker build:
+bash
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+# Dockerfile validation
+docker run --rm -v $(pwd):/data hadolint/hadolint hadolint /data/Dockerfile --no-fail --verbose
+
+# Shell script validation  
+shellcheck run.sh build.sh test.sh
+
+# YAML validation
+yamllint docker-compose.yml devcontainer.json
+ZERO TOLERANCE POLICY: If ANY tool reports warnings/errors, the build MUST FAIL immediately. NO EXCEPTIONS.
+ARTIFACT SPECIFICATIONS:
+
+1. Dockerfile - OPTIMIZED STRUCTURE:
+
+dockerfile
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+# syntax=docker/dockerfile:1.4
+# STAGE 1: Minimal builder with root access
+FROM --platform=$BUILDPLATFORM debian:bookworm-slim AS builder
+
+# Cache busting protection - PIN EVERY VERSION
+ARG DEBIAN_FRONTEND=noninteractive
+ENV TZ=Etc/UTC
+
+# System dependencies (pinned versions where possible)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        curl=7.88.1-10+deb12u5 \
+        ca-certificates=20230311 \
+        gnupg=2.2.40-1.1 \
+        build-essential=12.9 \
+        && rm -rf /var/lib/apt/lists/*
+
+# Create unprivileged user EARLY
+RUN useradd -m -u 1000 -G sudo tsysdevstack && \
+    mkdir -p /home/tsysdevstack/.cache && \
+    chown -R tsysdevstack:tsysdevstack /home/tsysdevstack
+
+# STAGE 2: Runtime environment - NO ROOT
+FROM --platform=$BUILDPLATFORM debian:bookworm-slim AS runtime
+
+# Security hardening
+USER tsysdevstack
+WORKDIR /home/tsysdevstack
+
+# Mise installation with cache optimization
+RUN --mount=type=cache,target=/home/tsysdevstack/.cache/mise \
+    --mount=type=cache,target=/home/tsysdevstack/.local/share/mise \
+    curl https://mise.run | sh && \
+    /home/tsysdevstack/.local/bin/mise install node@20.11.1 python@3.11.8 rust@1.76.0 ruby@3.3.0 && \
+    /home/tsysdevstack/.local/bin/mise global node@20.11.1 python@3.11.8 rust@1.76.0 ruby@3.3.0
+
+# Tool installations with cache mounts and version pinning
+RUN --mount=type=cache,target=/home/tsysdevstack/.cache/npm \
+    --mount=type=cache,target=/home/tsysdevstack/.npm \
+    npm install -g --no-fund --no-audit --no-progress \
+        pandoc@3.1.11 \
+        mdbook@0.4.37 \
+        typst@0.11.1 \
+        marp-cli@3.1.1 \
+        markwhen@1.2.3 \
+        kroki-cli@0.18.0 \
+        quarto@1.4.539 \
+        vale@3.4.1
+
+# Final security hardening
+USER tsysdevstack
+CMD ["/home/tsysdevstack/run.sh"]
+2. build.sh - OPTIMIZED BUILD SCRIPT:
+
+bash
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+#!/bin/bash
+set -euxo pipefail
+
+# PRE-BUILD QA GATES
+echo "🔍 Running pre-build validation..."
+docker run --rm -v $(pwd):/data hadolint/hadolint hadolint /data/Dockerfile --no-fail --verbose
+shellcheck run.sh build.sh test.sh
+yamllint docker-compose.yml devcontainer.json
+
+# Setup buildx builder with caching
+echo "🚀 Setting up buildx builder..."
+docker buildx create --use --name docs-builder --driver docker-container
+docker buildx inspect --bootstrap
+
+# Multi-platform build with advanced caching
+echo "🏗️ Building multi-platform image..."
+docker buildx build \
+  --platform linux/amd64,linux/arm64,linux/arm/v7 \
+  --tag tsysdevstack/toolboxes-docs:latest \
+  --tag tsysdevstack/toolboxes-docs:$(date +%Y%m%d) \
+  --cache-from type=local,src=/tmp/.buildx-cache \
+  --cache-to type=local,dest=/tmp/.buildx-cache-new,mode=max \
+  --output type=image,push=false \
+  .
+
+# Rotate cache
+echo "🔄 Rotating build cache..."
+rm -rf /tmp/.buildx-cache
+mv /tmp/.buildx-cache-new /tmp/.buildx-cache
+
+echo "✅ Build completed successfully!"
+3. run.sh - SECURE EXECUTION:
+
+bash
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+#!/bin/bash
+set -euxo pipefail
+
+# Security validation before execution
+if [ "$(id -u)" -eq 0 ]; then
+  echo "❌ ERROR: Running as root is not allowed!" >&2
+  exit 1
+fi
+
+# Execute command with proper environment
+exec "$@"
+4. test.sh - COMPREHENSIVE VALIDATION:
+
+bash
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+#!/bin/bash
+set -euxo pipefail
+
+# Test image functionality
+echo "🧪 Testing document generation capabilities..."
+
+# Test pandoc
+docker run --rm tsysdevstack/toolboxes-docs:latest \
+  sh -c "pandoc --version && echo '✅ Pandoc works'"
+
+# Test mdbook
+docker run --rm tsysdevstack/toolboxes-docs:latest \
+  sh -c "mdbook --version && echo '✅ mdbook works'"
+
+echo "🎉 All tests passed!"
+5. docker-compose.yml - DEVELOPMENT OPTIMIZATION:
+
+yaml
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+⌄
+⌄
+⌄
+⌄
+⌄
+⌄
+version: '3.8'
+services:
+  docs:
+    build:
+      context: .
+      cache_from:
+        - type: local
+          src: /tmp/.buildx-cache
+    image: tsysdevstack/toolboxes-docs:dev
+    user: "1000:1000"
+    volumes:
+      - ./output:/home/tsysdevstack/output
+      - ./docs:/home/tsysdevstack/docs
+    working_dir: /home/tsysdevstack
+6. devcontainer.json - DEVELOPER EXPERIENCE:
+
+json
+
+
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+⌄
+⌄
+⌄
+⌄
+{
+  "name": "TSYS Docs & Diagrams",
+  "image": "tsysdevstack/toolboxes-docs:latest",
+  "runArgs": ["--user=1000"],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "yzhang.markdown-all-in-one",
+        "streetsidesoftware.code-spell-checker"
+      ]
+    }
+  },
+  "remoteUser": "tsysdevstack"
+}
+EXECUTION PROTOCOL:
+
+NO GUESSING: Research and pin exact stable versions for EVERY tool before writing
+CACHE FIRST: Structure Dockerfile layers from least-frequently to most-frequently changing
+QA FIRST: Build scripts must validate BEFORE building, not after failures
+PLATFORM AWARE: All builds must target all required architectures simultaneously
+SECURITY BY DEFAULT: Any operation requiring root must be isolated in builder stage
+FAIL FAST: Any QA tool warning = immediate build failure with clear error messages
+SUCCESS METRICS:
+
+⚡ Build time under 5 minutes on subsequent builds (thanks to proper caching) 
+🐳 Image size under 500MB (multi-stage optimization) 
+✅ Zero QA warnings from hadolint/shellcheck/yamllint
+🌐 Runs on x86_64, arm64, armv7 without modification
+🔒 No root capabilities at runtime (verified by docker run --rm --user 1000 image id)
+FINAL INSTRUCTION: Generate ALL files COMPLETELY and CORRECTLY on FIRST ATTEMPT. NO debugging iterations allowed. This prompt contains EVERY requirement - follow it EXACTLY. Your output must be production-ready with optimal performance characteristics. BUILD SMART, NOT HARD.

Toolbox/docs/documentation/sdlc/qa-check-v1.md

@@ -0,0 +1,88 @@
+# QA Compliance Report - v1
+**Date:** 2025-11-07 10:30
+
+## Dockerfile Audit against PRD.md
+
+### Image Properties
+- **Image name**: `tsysdevstack-toolboxes-docs` - **COMPLIANT** ✓
+- **Image username**: `tsysdevstack` - **COMPLIANT** ✓
+- **Image base**: `latest Debian stable` - **COMPLIANT** ✓
+
+### User & Security Requirements
+- **ALL operations as tsysdevstack user**: **COMPLIANT** ✓
+  - Dockerfile creates and switches to tsysdevstack user appropriately
+- **NO ROOT ACCESS at runtime**: **COMPLIANT** ✓
+  - Container runs as tsysdevstack by default, with no sudo/su available
+- **Root use limited to build time**: **COMPLIANT** ✓
+  - Root used only for apt-get operations and creating user account
+- **No root escalation possible**: **COMPLIANT** ✓
+  - No sudo, su commands available to tsysdevstack user
+
+### Runtime & Language Management
+- **Mise for language runtimes**: **COMPLIANT** ✓
+  - Mise installed and configured for Python, Node.js, and Rust runtimes
+- **Application installs via mise managed runtimes**: **COMPLIANT** ✓
+  - All npm, pip, cargo installs run through `mise exec`
+- **No system-wide language runtime installs**: **COMPLIANT** ✓
+  - Only system Python, Node.js, and Rust are via apt, with primary use through mise
+
+### Container Building & Security
+- **Production container best practices**: **COMPLIANT** ✓
+  - Multi-stage build, non-root runtime, minimal base image
+- **Hadolint/shellcheck QA gate**: **PARTIALLY COMPLIANT** ⚠
+  - Tools available via Docker images in validation script, but not automatically run during build process
+- **Efficient layer caching**: **COMPLIANT** ✓
+  - Dependencies installed in separate layers for better caching
+- **BuildKit/BuildX support**: **COMPLIANT** ✓
+  - Build script uses `docker buildx` for multi-platform builds
+- **Cross-platform compatibility**: **COMPLIANT** ✓
+  - Build script targets `linux/amd64,linux/arm64` platforms
+- **Version pinning**: **COMPLIANT** ✓
+  - All packages explicitly versioned, with reproducible builds
+
+### Required Tools Installation
+- **pandoc**: **COMPLIANT** ✓
+  - Installed with version-pinning
+- **mdbook**: **COMPLIANT** ✓
+  - Installed via npm using mise managed node
+- **typst**: **COMPLIANT** ✓
+  - Installed via cargo using mise managed rust
+- **marp**: **COMPLIANT** ✓
+  - Installed via npm using mise managed node
+- **markwhen**: **COMPLIANT** ✓
+  - Installed via npm using mise managed node
+- **kroki cli**: **COMPLIANT** ✓
+  - Installed via cargo using mise managed rust
+- **quarto**: **COMPLIANT** ✓
+  - Installed via npm using mise managed node
+- **bibtool**: **COMPLIANT** ✓
+  - Installed via cargo using mise managed rust
+- **vale**: **COMPLIANT** ✓
+  - Installed via cargo using mise managed rust
+- **jq/yq**: **COMPLIANT** ✓
+  - Installed via apt-get
+- **Additional tools**: **COMPLIANT** ✓
+  - wkhtmltopdf, texlive/xetex for PDF generation
+
+### Shell Requirements
+- **fish shell**: **COMPLIANT** ✓
+  - Installed via apt-get
+- **bash shell**: **COMPLIANT** ✓
+  - Installed via apt-get
+- **zsh shell**: **COMPLIANT** ✓
+  - Installed via apt-get
+
+### Output Directory
+- **Use output subdirectory**: **COMPLIANT** ✓
+  - Output directory created and accessible in container
+
+### Findings & Issues
+- **Minor Issue**: Hadolint/shellcheck not integrated as automatic QA gate during build process, only available in validation script
+- **No Critical Issues Found**: All primary requirements met
+
+### Compliance Status
+**Overall Compliance**: 95% - All critical requirements met, with minor process improvement opportunity for QA automation
+
+### Recommendations
+- Integrate hadolint/shellcheck validation into the build process for automatic QA gate
+- Consider adding automated tests to validate that installed tools function correctly