BIO-QMS Publish CLI Command Technical Specification

Table of Contents

1. Executive Summary
2. Overview
3. CLI Interface Specification
4. Workflow Stages
5. Command-Line Flags
6. Interactive Mode
7. Non-Interactive Mode
8. Output Format Specification
9. Error Handling
10. Rollback Command
11. Version Management
12. Deployment History
13. CODITECT Framework Integration
14. Notification Hooks
15. Authentication and Authorization
16. Multi-Project Support
17. Caching and Optimization
18. Troubleshooting Guide
19. Package.json Scripts
20. Implementation Notes

---

Executive Summary

The BIO-QMS publish CLI command provides one-click deployment from source code to live documentation platform. It orchestrates six workflow stages—pre-flight validation, manifest validation, build, test, deploy, and verify—ensuring regulatory compliance, quality gates, and zero-downtime deployments.

Primary Use Cases:

• Developer Local Publish: npm run publish for development/staging deployments
• CI/CD Pipeline: npm run publish -- --env prod --yes --json for automated production releases
• Emergency Rollback: npm run publish -- --rollback latest to revert to previous working state
• CODITECT Integration: /docs-deploy --project bio-qms for framework-orchestrated deployments

Key Design Principles:

• Safety First: Multiple validation gates before production deployment
• Transparency: Detailed progress indicators and comprehensive logging
• Fail Fast: Early detection of issues with clear error messages
• Atomic Operations: All-or-nothing deployments with automatic rollback on failure
• Audit Trail: Complete deployment history for regulatory compliance

---

Overview

Purpose

The publish CLI command serves as the single source of truth for deployment orchestration in the BIO-QMS platform. It eliminates manual steps, reduces deployment errors, and ensures consistent processes across development, staging, and production environments.

Architecture Context

┌─────────────────────────────────────────────────────────────────┐
│                      Publish CLI Command                        │
│                    (scripts/publish.sh)                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ├─── Stage 1: Pre-flight Validation
                              │    ├─ Git status check
                              │    ├─ Dependency verification
                              │    ├─ GCP authentication
                              │    └─ Environment detection
                              │
                              ├─── Stage 2: Manifest Validation
                              │    ├─ JSON Schema compliance
                              │    ├─ Referential integrity
                              │    └─ Document readiness
                              │
                              ├─── Stage 3: Build
                              │    ├─ Vite production build
                              │    ├─ Size budget check
                              │    └─ Asset optimization
                              │
                              ├─── Stage 4: Test
                              │    ├─ Smoke tests on dist/
                              │    ├─ Accessibility check
                              │    └─ Broken link validation
                              │
                              ├─── Stage 5: Deploy
                              │    ├─ Container build & push
                              │    ├─ Cloud Run deploy
                              │    └─ Health check
                              │
                              └─── Stage 6: Verify
                                   ├─ HTTP probe of live site
                                   ├─ Version comparison
                                   └─ Production smoke test

Design Goals

Goal	Implementation
One-Click Deployment	Single command from code to live docs
Regulatory Compliance	Audit trail, validation gates, version tracking
Developer Experience	Clear progress, helpful errors, fast feedback
CI/CD Integration	JSON output, exit codes, non-interactive mode
Safety & Reliability	Pre-flight checks, rollback capability, health validation

---

CLI Interface Specification

Primary Entry Point

npm run publish [-- <flags>]

Description: Primary user-facing command defined in package.json scripts section. Delegates to scripts/publish.sh orchestration script.

Examples:

# Development deployment (interactive)
npm run publish

# Staging deployment with verbose output
npm run publish -- --env staging --verbose

# Production deployment (CI/CD)
npm run publish -- --env prod --yes --json

# Dry-run to preview actions
npm run publish -- --dry-run

# Emergency rollback
npm run publish -- --rollback latest

Underlying Orchestration Script

./scripts/publish.sh [OPTIONS]

Description: Bash orchestration script implementing the six-stage deployment workflow. Can be invoked directly for advanced use cases or debugging.

Location: scripts/publish.sh

Requirements:

• Bash 4.0+ (for associative arrays)
• Node.js 18+ (for Vite build)
• gcloud CLI (for GCP deployment)
• jq (for JSON manipulation)
• docker (for container builds)

CODITECT Framework Integration

/docs-deploy --project bio-qms [--env dev|staging|prod] [--rollback <revision>]

Description: CODITECT framework command wrapping the publish CLI for integrated deployment orchestration across multiple projects.

Location: ~/.coditect/commands/docs-deploy.md

Implementation: Delegates to project-specific npm run publish with framework context (logging, notifications, multi-project coordination).

---

Workflow Stages

Stage 1: Pre-flight Validation

Purpose: Verify environment readiness before starting deployment.

Checks:

Check	Validation	Failure Action
Git Status	Working directory clean (no uncommitted changes)	ERROR: Commit or stash changes
Git Branch	On main or develop branch for prod/staging	WARNING: Deploying from feature branch
Dependencies	node_modules/ exists and up-to-date	RUN: npm install
GCP Auth	Valid gcloud auth credentials	ERROR: Run gcloud auth login
GCP Project	Correct project selected for environment	ERROR: Run gcloud config set project <project>
Docker Running	Docker daemon accessible	ERROR: Start Docker Desktop
Required Tools	gcloud, docker, jq, curl available	ERROR: Install missing tools
Environment Variables	Required vars set (e.g., GCP_PROJECT_ID)	ERROR: Set missing variables

Output Example:

=== Stage 1: Pre-flight Validation ===
✓ Git status clean (no uncommitted changes)
✓ Current branch: main
✓ Dependencies installed (1,234 packages)
✓ GCP authenticated as user@example.com
✓ GCP project: coditect-bio-qms-prod
✓ Docker daemon running
✓ Required tools available: gcloud, docker, jq, curl
✓ Environment variables set: GCP_PROJECT_ID, CLOUD_RUN_SERVICE

Stage 1: PASS (8/8 checks) — 2.3s

Stage 2: Manifest Validation

Purpose: Ensure publish.json is valid and all referenced documents exist.

Validation Steps:

1. Generate Manifest: Run npm run generate-manifest
2. Schema Validation: Validate public/publish.json against JSON Schema
3. Referential Integrity: Verify all document paths in manifest exist on disk
4. Document Readiness: Run scripts/check-doc-readiness.sh all
5. Metadata Completeness: Check all docs have required frontmatter fields

Schema Validation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["project_name", "version", "documents"],
  "properties": {
    "project_name": { "type": "string" },
    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
    "generated_at": { "type": "string", "format": "date-time" },
    "total_documents": { "type": "integer", "minimum": 0 },
    "categories": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "count"],
        "properties": {
          "name": { "type": "string" },
          "count": { "type": "integer", "minimum": 0 }
        }
      }
    },
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "title", "path", "type"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "path": { "type": "string" },
          "type": { "enum": ["markdown", "dashboard"] },
          "audience": { "type": "string" },
          "category": { "type": "string" },
          "keywords": { "type": "array", "items": { "type": "string" } },
          "summary": { "type": "string" },
          "status": { "enum": ["active", "draft", "archived"] }
        }
      }
    }
  }
}

Output Example:

=== Stage 2: Manifest Validation ===
✓ Manifest generated: 247 documents across 12 categories
✓ JSON Schema validation passed
✓ Referential integrity: 247/247 documents exist on disk
✓ Document readiness: Sprint S1-S10 all clear
✓ Metadata completeness: 247/247 docs have required fields

Stage 2: PASS — 3.8s

Stage 3: Build

Purpose: Compile production-optimized static site bundle.

Build Process:

1. Clean Build Directory: Remove dist/ to ensure clean build
2. Vite Build: Run npm run build (includes manifest generation)
3. Size Budget Check: Verify bundle size within acceptable limits
4. Asset Verification: Confirm critical assets present (index.html, JS chunks, CSS)
5. Build Manifest: Generate dist/build-manifest.json with asset hashes

Size Budget Targets:

Asset Type	Target	Warning	Error
Total Bundle	< 2 MB	> 2 MB	> 5 MB
JS Chunks	< 500 KB each	> 500 KB	> 1 MB
CSS Bundle	< 200 KB	> 200 KB	> 500 KB
Images	< 100 KB each	> 100 KB	> 500 KB

Output Example:

=== Stage 3: Build ===
✓ Build directory cleaned
✓ Vite production build completed

  Build Output:
  dist/index.html                     12.3 kB
  dist/assets/index-a8f9e4c2.js      342.7 kB (gzip: 98.4 kB)
  dist/assets/vendor-1b2c3d4e.js    456.2 kB (gzip: 134.7 kB)
  dist/assets/index-5e6f7a8b.css    123.4 kB (gzip: 28.9 kB)

✓ Size budget check passed (total: 1.89 MB)
✓ Critical assets verified: index.html, 12 JS chunks, 3 CSS files
✓ Build manifest generated with asset hashes

Stage 3: PASS — 18.7s

Stage 4: Test

Purpose: Validate built output before deployment.

Test Suite:

Test Type	Description	Failure Action
Smoke Tests	Verify core pages render without errors	ERROR: Fix broken pages
Accessibility	Check WCAG 2.1 AA compliance (axe-core)	WARNING: Fix accessibility issues
Broken Links	Scan all internal links for 404s	ERROR: Fix broken links
Asset Integrity	Verify all assets load (no 404s)	ERROR: Fix missing assets
Search Index	Verify MiniSearch index builds	ERROR: Fix search data
Performance	Check Lighthouse scores (optional)	WARNING: Optimize performance

Test Execution:

# Start local server on dist/
npx vite preview --port 4173 &
SERVER_PID=$!

# Wait for server ready
wait-for-port 4173

# Run test suite
node tests/smoke-test.js
node tests/accessibility-test.js
node tests/broken-links-test.js

# Cleanup
kill $SERVER_PID

Output Example:

=== Stage 4: Test ===
✓ Local preview server started on http://localhost:4173
✓ Smoke tests: 8/8 pages render successfully
  - Home page: 200 OK (234ms)
  - Documentation: 200 OK (189ms)
  - Architecture: 200 OK (212ms)
  - Compliance: 200 OK (198ms)
  - Operations: 200 OK (176ms)
  - Reference: 200 OK (203ms)
  - Project Tracking: 200 OK (187ms)
  - Search: 200 OK (156ms)

✓ Accessibility: 0 violations, 2 warnings
  ⚠ Minor: Color contrast on secondary buttons (WCAG AAA only)

✓ Broken links: 0/347 links broken
✓ Asset integrity: 127/127 assets load successfully
✓ Search index: 247 documents indexed

Stage 4: PASS (2 warnings) — 12.4s

Stage 5: Deploy

Purpose: Build container, push to registry, deploy to Cloud Run.

Deployment Process:

1. Container Build: Build Docker image with Nginx serving static files
2. Image Tag: Tag with version and environment (e.g., v1.2.3-prod)
3. Registry Push: Push to GCP Artifact Registry
4. Cloud Run Deploy: Deploy new revision to Cloud Run service
5. Traffic Migration: Gradual traffic shift (0% → 100%)
6. Health Check: Verify new revision passes health checks
7. Traffic Commit: Commit 100% traffic to new revision

Dockerfile:

# Multi-stage build for optimized production image
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

Cloud Run Configuration:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: bio-qms-docs
  namespace: coditect-prod
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/minScale: "1"
        autoscaling.knative.dev/maxScale: "10"
    spec:
      containerConcurrency: 80
      containers:
      - image: us-central1-docker.pkg.dev/coditect-bio-qms-prod/bio-qms/docs:v1.2.3-prod
        ports:
        - containerPort: 8080
        resources:
          limits:
            cpu: "1"
            memory: 512Mi
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10

Output Example:

=== Stage 5: Deploy ===
✓ Container build started (build ID: 1a2b3c4d)
  Building image: us-central1-docker.pkg.dev/coditect-bio-qms-prod/bio-qms/docs:v1.2.3-prod

✓ Container build completed (42.3s)
  Image size: 87.4 MB (compressed: 32.1 MB)

✓ Image pushed to Artifact Registry
  Digest: sha256:9f8e7d6c5b4a3...

✓ Cloud Run deployment initiated
  Service: bio-qms-docs
  Region: us-central1
  Revision: bio-qms-docs-v123-prod-20260216-143022

✓ Traffic migration: 0% → 25% → 50% → 75% → 100%
✓ Health checks passing (3/3 probes successful)
✓ Traffic committed to new revision

Deployment URL: https://bio-qms-docs-abc123-uc.a.run.app

Stage 5: PASS — 87.6s

Stage 6: Verify

Purpose: Confirm live site is operational and serving correct version.

Verification Tests:

Test	Description	Failure Action
HTTP Probe	GET request to deployment URL	ERROR: Rollback immediately
Version Check	Verify deployed version matches build	ERROR: Rollback immediately
Smoke Test	Load critical pages on live site	ERROR: Rollback immediately
Performance	Check response times < 500ms	WARNING: Investigate performance
SSL/TLS	Verify valid HTTPS certificate	ERROR: Fix certificate issue
CDN Cache	Confirm CDN cache invalidated	WARNING: Manually purge cache

Output Example:

=== Stage 6: Verify ===
✓ HTTP probe: 200 OK (https://bio-qms-docs-abc123-uc.a.run.app)
✓ Version verification: v1.2.3-prod deployed successfully
✓ Production smoke test: 8/8 pages load successfully
  - Average response time: 187ms
  - P95 response time: 342ms
  - P99 response time: 476ms

✓ HTTPS certificate valid (expires: 2026-05-16)
✓ CDN cache invalidated (CloudFlare purge: 1,234 URLs)

Stage 6: PASS — 8.9s

════════════════════════════════════════════════════════════════
✓ DEPLOYMENT SUCCESSFUL

Version:      v1.2.3-prod
Environment:  production
URL:          https://bio-qms-docs-abc123-uc.a.run.app
Revision:     bio-qms-docs-v123-prod-20260216-143022
Deployed:     2026-02-16T14:32:45Z
Duration:     134.1s

Deployment ID: dep-20260216-143022-a1b2c3
════════════════════════════════════════════════════════════════

---

Command-Line Flags

Environment Selection

--env <environment>

Values: dev, staging, prod

Default: dev (determined from git branch or environment variable)

Description: Target deployment environment.

Behavior:

• dev: Deploy to development Cloud Run service, minimal validation
• staging: Deploy to staging service, full validation, no production confirmation
• prod: Deploy to production service, full validation, requires confirmation (unless --yes)

Examples:

npm run publish -- --env dev        # Development deployment
npm run publish -- --env staging    # Staging deployment
npm run publish -- --env prod       # Production deployment (interactive)

Dry-Run Mode

--dry-run

Description: Execute all validation and build steps but skip actual deployment.

Use Cases:

• Preview deployment actions before committing
• Validate build locally before CI/CD run
• Troubleshoot deployment issues

Output: All stages execute except Stage 5 (Deploy) which shows planned actions without executing.

Example:

npm run publish -- --env prod --dry-run
# Output: Shows what WOULD happen without deploying

Skip Tests

--skip-tests

Description: Skip Stage 4 (Test) validation.

Warning: Use only in emergencies or trusted CI/CD pipelines. Skipping tests can deploy broken builds.

Recommended: Use --dry-run first to validate build quality.

Example:

npm run publish -- --env dev --skip-tests

Force Deployment

--force

Description: Override validation failures and deploy anyway.

Use Cases:

• Emergency hotfix deployment
• Override size budget warnings
• Deploy with known accessibility issues (with approval)

Warning: Requires justification comment when used in production.

Example:

npm run publish -- --env prod --force --comment "Emergency fix for CVE-2026-12345"

Rollback

--rollback <revision>

Values: latest, previous, specific revision ID (e.g., bio-qms-docs-v122-prod-20260215-183045)

Description: Rollback to a previous Cloud Run revision.

Behavior:

• latest: Rollback to most recent successful deployment
• previous: Rollback to deployment before current
• <revision-id>: Rollback to specific revision

Safety: Rollback executes immediately without confirmation (to enable emergency recovery).

Example:

npm run publish -- --rollback latest
npm run publish -- --rollback bio-qms-docs-v122-prod-20260215-183045

Version Override

--version <semver>

Description: Manually specify deployment version instead of auto-increment.

Format: Semantic versioning MAJOR.MINOR.PATCH (e.g., 1.2.3)

Validation: Version must be greater than current deployed version.

Use Cases:

• Hotfix version numbering (e.g., 1.2.4 after 1.2.3)
• Major version bump (e.g., 2.0.0)

Example:

npm run publish -- --version 1.3.0

Verbose Output

--verbose

Description: Enable detailed debug logging.

Output:

• Full command output (not just summaries)
• Timing information for each substep
• Environment variable values
• API request/response details

Example:

npm run publish -- --env prod --verbose > deploy.log 2>&1

JSON Output

--json

Description: Output machine-readable JSON instead of human-readable text.

Use Cases:

• CI/CD pipeline integration
• Deployment dashboards
• Automated monitoring/alerting

Output Format:

{
  "status": "success",
  "version": "1.2.3",
  "environment": "prod",
  "deployment_id": "dep-20260216-143022-a1b2c3",
  "revision": "bio-qms-docs-v123-prod-20260216-143022",
  "url": "https://bio-qms-docs-abc123-uc.a.run.app",
  "deployed_at": "2026-02-16T14:32:45Z",
  "duration_seconds": 134.1,
  "stages": {
    "preflight": { "status": "pass", "duration": 2.3, "checks": 8 },
    "validate": { "status": "pass", "duration": 3.8, "documents": 247 },
    "build": { "status": "pass", "duration": 18.7, "size_mb": 1.89 },
    "test": { "status": "pass", "duration": 12.4, "warnings": 2 },
    "deploy": { "status": "pass", "duration": 87.6 },
    "verify": { "status": "pass", "duration": 8.9 }
  }
}

Example:

RESULT=$(npm run publish -- --env prod --yes --json)
echo "$RESULT" | jq '.url'

Non-Interactive Confirmation

--yes

Description: Auto-confirm all interactive prompts (for CI/CD).

Use Cases:

• Automated deployments in CI/CD
• Scheduled deployments
• Scripted multi-project deployments

Warning: Bypasses production safety confirmation. Use only in trusted CI/CD pipelines.

Example:

npm run publish -- --env prod --yes --json

---

Interactive Mode

Production Confirmation Prompt

When deploying to production without --yes flag, interactive confirmation is required:

════════════════════════════════════════════════════════════════
Production Deployment Confirmation
════════════════════════════════════════════════════════════════

Target Environment:  production
Version:             v1.2.3-prod
Current Version:     v1.2.2-prod
Service:             bio-qms-docs
Region:              us-central1

Changes in this deployment:
  • 14 documents updated
  • 3 new documents added
  • 1 document removed
  • Build size: 1.89 MB (0.12 MB larger than previous)

Validation Results:
  ✓ Pre-flight: PASS (8/8 checks)
  ✓ Manifest:   PASS (247 documents)
  ✓ Build:      PASS (size budget OK)
  ✓ Test:       PASS (2 warnings)

⚠ Warnings:
  • Color contrast on secondary buttons (WCAG AAA)
  • Build size increased 6.8% from previous deployment

Do you want to proceed with production deployment? [y/N]

User Input:

• y or yes: Proceed with deployment
• n or no: Abort deployment
• d or diff: Show detailed diff of changes
• r or review: Re-run validation stages

Diff Summary

When user requests diff (d):

════════════════════════════════════════════════════════════════
Deployment Diff Summary
════════════════════════════════════════════════════════════════

Modified Documents (14):
  docs/architecture/system-design.md      (23 lines changed)
  docs/compliance/hipaa-controls.md       (8 lines changed)
  docs/operations/deployment-guide.md     (45 lines changed)
  [... 11 more ...]

Added Documents (3):
  docs/reference/api-endpoints.md         (342 lines)
  docs/reference/error-codes.md           (128 lines)
  docs/security/threat-model.md           (267 lines)

Removed Documents (1):
  docs/legacy/deprecated-api.md           (removed)

Asset Changes:
  index.html:          12.1 kB → 12.3 kB (+0.2 kB)
  main.js:            342.3 kB → 342.7 kB (+0.4 kB)
  vendor.js:          455.8 kB → 456.2 kB (+0.4 kB)
  styles.css:         122.9 kB → 123.4 kB (+0.5 kB)

Continue with deployment? [y/N]

---

Non-Interactive Mode

CI/CD Integration

For automated deployments, use non-interactive mode with JSON output:

npm run publish -- --env prod --yes --json > deploy-result.json
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "Deployment successful"
  DEPLOYMENT_URL=$(jq -r '.url' deploy-result.json)
  echo "::set-output name=url::$DEPLOYMENT_URL"
else
  echo "Deployment failed"
  jq -r '.error' deploy-result.json
  exit 1
fi

Exit Codes

Exit Code	Meaning	CI/CD Action
0	Success	Continue pipeline
1	Pre-flight validation failed	Fail build
2	Manifest validation failed	Fail build
3	Build failed	Fail build
4	Tests failed	Fail build (or warn if --skip-tests allowed)
5	Deployment failed	Fail build, trigger rollback
6	Verification failed	Fail build, trigger rollback
7	Rollback failed	Critical alert
8	Authentication failed	Fix credentials
9	Permission denied	Fix IAM roles
10	Timeout	Retry or escalate

GitHub Actions Example

name: Deploy to Production

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Authenticate to GCP
        uses: google-github-actions/auth@v1
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}

      - name: Deploy to Production
        id: deploy
        run: |
          npm run publish -- --env prod --yes --json > deploy-result.json
          echo "url=$(jq -r '.url' deploy-result.json)" >> $GITHUB_OUTPUT
          echo "version=$(jq -r '.version' deploy-result.json)" >> $GITHUB_OUTPUT

      - name: Notify Slack
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "BIO-QMS Docs deployed to production",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "✓ *BIO-QMS Docs Deployed*\n\nVersion: `${{ steps.deploy.outputs.version }}`\nURL: ${{ steps.deploy.outputs.url }}"
                  }
                }
              ]
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

      - name: Rollback on Failure
        if: failure()
        run: npm run publish -- --rollback latest

---

Output Format Specification

Human-Readable Output

Default output format for terminal use:

════════════════════════════════════════════════════════════════
BIO-QMS Docs Publish v1.0.0
════════════════════════════════════════════════════════════════

Target:      production
Version:     v1.2.3-prod
Started:     2026-02-16T14:28:32Z

=== Stage 1: Pre-flight Validation ===
✓ Git status clean
✓ Dependencies installed
✓ GCP authenticated
✓ Docker running
Stage 1: PASS — 2.3s

=== Stage 2: Manifest Validation ===
✓ Manifest generated: 247 documents
✓ Schema validation passed
✓ Referential integrity verified
Stage 2: PASS — 3.8s

=== Stage 3: Build ===
✓ Vite build completed
✓ Size budget check passed
✓ Assets verified
Stage 3: PASS — 18.7s

=== Stage 4: Test ===
✓ Smoke tests: 8/8 passed
✓ Accessibility: 0 violations
✓ Broken links: 0 found
Stage 4: PASS (2 warnings) — 12.4s

=== Stage 5: Deploy ===
✓ Container built and pushed
✓ Cloud Run deployed
✓ Health checks passed
Stage 5: PASS — 87.6s

=== Stage 6: Verify ===
✓ HTTP probe successful
✓ Version verified
✓ Production smoke test passed
Stage 6: PASS — 8.9s

════════════════════════════════════════════════════════════════
✓ DEPLOYMENT SUCCESSFUL

Version:      v1.2.3-prod
Environment:  production
URL:          https://bio-qms-docs-abc123-uc.a.run.app
Deployed:     2026-02-16T14:32:45Z
Duration:     134.1s
════════════════════════════════════════════════════════════════

JSON Output

Machine-readable output for CI/CD integration (--json flag):

{
  "status": "success",
  "timestamp": "2026-02-16T14:32:45Z",
  "version": "1.2.3",
  "environment": "prod",
  "deployment_id": "dep-20260216-143022-a1b2c3",
  "revision": "bio-qms-docs-v123-prod-20260216-143022",
  "url": "https://bio-qms-docs-abc123-uc.a.run.app",
  "deployed_at": "2026-02-16T14:32:45Z",
  "duration_seconds": 134.1,
  "git": {
    "branch": "main",
    "commit": "a1b2c3d4e5f6",
    "author": "user@example.com",
    "message": "feat: Add API reference documentation"
  },
  "stages": {
    "preflight": {
      "status": "pass",
      "duration": 2.3,
      "checks": {
        "git_status": "pass",
        "dependencies": "pass",
        "gcp_auth": "pass",
        "docker": "pass",
        "tools": "pass",
        "env_vars": "pass"
      }
    },
    "validate": {
      "status": "pass",
      "duration": 3.8,
      "documents": 247,
      "categories": 12,
      "schema_valid": true,
      "referential_integrity": true
    },
    "build": {
      "status": "pass",
      "duration": 18.7,
      "size_mb": 1.89,
      "size_budget_ok": true,
      "assets": {
        "js_chunks": 12,
        "css_files": 3,
        "images": 87,
        "total_files": 127
      }
    },
    "test": {
      "status": "pass",
      "duration": 12.4,
      "smoke_tests": { "passed": 8, "failed": 0 },
      "accessibility": { "violations": 0, "warnings": 2 },
      "broken_links": { "total": 347, "broken": 0 },
      "warnings": [
        "Color contrast on secondary buttons (WCAG AAA)",
        "Build size increased 6.8% from previous deployment"
      ]
    },
    "deploy": {
      "status": "pass",
      "duration": 87.6,
      "container_build_seconds": 42.3,
      "container_size_mb": 87.4,
      "image_digest": "sha256:9f8e7d6c5b4a3...",
      "service": "bio-qms-docs",
      "region": "us-central1",
      "traffic_migration_seconds": 28.5
    },
    "verify": {
      "status": "pass",
      "duration": 8.9,
      "http_probe": "200 OK",
      "version_match": true,
      "smoke_test_passed": true,
      "response_times": {
        "avg_ms": 187,
        "p95_ms": 342,
        "p99_ms": 476
      }
    }
  },
  "changes": {
    "documents_updated": 14,
    "documents_added": 3,
    "documents_removed": 1,
    "size_change_mb": 0.12
  }
}

Error Output

When deployment fails:

{
  "status": "error",
  "timestamp": "2026-02-16T14:35:21Z",
  "error": {
    "stage": "test",
    "code": "BROKEN_LINKS",
    "message": "3 broken links detected",
    "details": [
      {
        "source": "docs/architecture/system-design.md",
        "target": "/docs/reference/api-spec.md",
        "error": "404 Not Found"
      },
      {
        "source": "docs/compliance/hipaa-controls.md",
        "target": "/docs/security/encryption.md",
        "error": "404 Not Found"
      },
      {
        "source": "docs/operations/runbook.md",
        "target": "/dashboards/metrics",
        "error": "404 Not Found"
      }
    ],
    "suggestion": "Fix broken links before deploying. Run 'npm run test:links' to validate."
  },
  "stages_completed": ["preflight", "validate", "build"],
  "stages_failed": ["test"],
  "exit_code": 4
}

---

Error Handling

Error Classification

Error Type	Severity	Recovery Action
Pre-flight	HIGH	Fix environment, retry
Validation	HIGH	Fix manifest, retry
Build	HIGH	Fix build errors, retry
Test	MEDIUM	Fix issues or override with --force
Deploy	CRITICAL	Automatic rollback
Verify	CRITICAL	Automatic rollback

Automatic Rollback Triggers

Automatic rollback occurs when:

1. Deploy Stage Failure:

   • Container build fails
   • Image push fails
   • Cloud Run deployment fails
   • Health checks fail after 3 retries

2. Verify Stage Failure:

   • HTTP probe returns non-200 status
   • Version mismatch detected
   • Production smoke tests fail

3. Manual Trigger:

   • User aborts during deployment
   • Timeout exceeded (10 minutes default)

Rollback Process

=== AUTOMATIC ROLLBACK INITIATED ===

Reason:      Verification failed (HTTP probe: 503 Service Unavailable)
Failed At:   Stage 6 (Verify)
New Revision: bio-qms-docs-v123-prod-20260216-143022
Rollback To:  bio-qms-docs-v122-prod-20260215-183045

Rolling back...
✓ Traffic shifted to previous revision (100%)
✓ New revision stopped
✓ Health checks passing on previous revision
✓ Rollback completed (8.3s)

Current URL: https://bio-qms-docs-abc123-uc.a.run.app
Current Version: v1.2.2-prod

Deployment failed. No changes were made to production.
Logs saved to: .deployment/logs/failed-dep-20260216-143022.log

Common Errors and Resolutions

Error: Git Working Directory Not Clean

ERROR: Git working directory has uncommitted changes.
Commit or stash changes before deploying.

Uncommitted files:
  M docs/architecture/system-design.md
  ?? docs/new-document.md

Resolution:
  git add .
  git commit -m "Your commit message"

  OR

  git stash
  npm run publish
  git stash pop

Error: GCP Authentication Failed

ERROR: GCP authentication failed.
User not authenticated or credentials expired.

Resolution:
  gcloud auth login
  gcloud auth application-default login

For CI/CD:
  gcloud auth activate-service-account --key-file=sa-key.json

Error: Size Budget Exceeded

ERROR: Build size exceeds budget.

Actual:   5.23 MB
Budget:   5.00 MB
Excess:   0.23 MB (4.6% over budget)

Largest assets:
  vendor.js:     2.34 MB (45%)
  images/:       1.89 MB (36%)
  main.js:       0.87 MB (17%)

Resolution:
  1. Code-split large vendor bundles
  2. Optimize/compress images
  3. Use dynamic imports for routes
  4. Override with --force (not recommended)

Error: Broken Links Detected

ERROR: 3 broken links detected.

docs/architecture/system-design.md:
  → /docs/reference/api-spec.md (404 Not Found)

docs/compliance/hipaa-controls.md:
  → /docs/security/encryption.md (404 Not Found)

docs/operations/runbook.md:
  → /dashboards/metrics (404 Not Found)

Resolution:
  1. Fix broken links in source documents
  2. Run 'npm run test:links' to validate
  3. Override with --force (not recommended for production)

Error: Cloud Run Deployment Failed

ERROR: Cloud Run deployment failed.

Service:  bio-qms-docs
Region:   us-central1
Revision: bio-qms-docs-v123-prod-20260216-143022

Error Details:
  Container failed to start. Logs:

  2026-02-16T14:30:12.345Z ERROR: Port 8080 already in use
  2026-02-16T14:30:12.456Z ERROR: Application startup failed

Resolution:
  1. Check container logs: gcloud run logs read --service=bio-qms-docs
  2. Test container locally: docker run -p 8080:8080 <image>
  3. Verify Dockerfile configuration

Automatic rollback initiated...
✓ Rollback completed. Production unchanged.

---

Rollback Command

Usage

npm run publish -- --rollback <revision>

Rollback Targets

Target	Description	Example
latest	Most recent successful deployment	--rollback latest
previous	Deployment before current	--rollback previous
<revision-id>	Specific Cloud Run revision	--rollback bio-qms-docs-v122-prod-20260215-183045
v<semver>	Specific version number	--rollback v1.2.2

List Available Revisions

npm run publish -- --list-revisions

Available Revisions:
  v1.2.3-prod  bio-qms-docs-v123-prod-20260216-143022  2026-02-16T14:32:45Z  SERVING (100% traffic)
  v1.2.2-prod  bio-qms-docs-v122-prod-20260215-183045  2026-02-15T18:30:45Z  READY
  v1.2.1-prod  bio-qms-docs-v121-prod-20260214-091234  2026-02-14T09:12:34Z  READY
  v1.2.0-prod  bio-qms-docs-v120-prod-20260213-163521  2026-02-13T16:35:21Z  RETIRED
  v1.1.9-prod  bio-qms-docs-v119-prod-20260212-145032  2026-02-12T14:50:32Z  RETIRED

Rollback Execution

npm run publish -- --rollback latest

=== ROLLBACK INITIATED ===

Current Version:  v1.2.3-prod
Target Version:   v1.2.2-prod
Target Revision:  bio-qms-docs-v122-prod-20260215-183045

Rollback will:
  1. Shift 100% traffic to target revision
  2. Verify health checks pass
  3. Stop current revision (optional)

Proceed with rollback? [y/N] y

Rolling back...
✓ Traffic shifted to v1.2.2-prod (100%)
✓ Health checks passing (3/3 probes)
✓ Current revision stopped

═══════════════════════════════════════════════
✓ ROLLBACK SUCCESSFUL

Version:     v1.2.2-prod
Revision:    bio-qms-docs-v122-prod-20260215-183045
URL:         https://bio-qms-docs-abc123-uc.a.run.app
Rolled Back: 2026-02-16T14:45:12Z
Duration:    8.3s
═══════════════════════════════════════════════

Rollback Verification

After rollback, verification tests run automatically:

=== Rollback Verification ===
✓ HTTP probe: 200 OK
✓ Version check: v1.2.2-prod confirmed
✓ Smoke tests: 8/8 passed
✓ Response times: avg 178ms, P99 423ms

Rollback verified. Service operational.

---

Version Management

Version Numbering

BIO-QMS follows Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH[-ENV]

Examples:
  1.0.0-dev       # Development deployment
  1.0.0-staging   # Staging deployment
  1.0.0-prod      # Production deployment
  1.1.0-prod      # Minor version bump
  2.0.0-prod      # Major version bump

Auto-Increment Rules

Change Type	Version Bump	Example
New document	PATCH	1.2.3 → 1.2.4
Updated document	PATCH	1.2.3 → 1.2.4
New feature	MINOR	1.2.3 → 1.3.0
Breaking change	MAJOR	1.2.3 → 2.0.0
Hotfix	PATCH	1.2.3 → 1.2.4

Version Detection

# Auto-detect version bump based on changes
CURRENT_VERSION=$(gcloud run revisions describe <service> --format='value(metadata.labels.version)')
CHANGE_TYPE=$(detect-change-type)  # analyzes git diff

case "$CHANGE_TYPE" in
  breaking) NEXT_VERSION=$(semver-bump major "$CURRENT_VERSION") ;;
  feature)  NEXT_VERSION=$(semver-bump minor "$CURRENT_VERSION") ;;
  *)        NEXT_VERSION=$(semver-bump patch "$CURRENT_VERSION") ;;
esac

Manual Version Override

npm run publish -- --version 2.0.0

Version Override:
  Current: v1.2.3-prod
  Manual:  v2.0.0-prod

This is a MAJOR version bump.
Reason: Breaking changes in API documentation structure.

Proceed? [y/N]

Git Tagging

Successful production deployments automatically create Git tags:

git tag -a v1.2.3-prod -m "Release v1.2.3 to production"
git push origin v1.2.3-prod

Version Validation

Before deployment, version is validated:

Version Validation:
  ✓ Format valid (semver)
  ✓ Greater than current version
  ✓ Not already deployed
  ✓ Git tag available

---

Deployment History

Local Deployment Log

All deployments are logged to .deployment/history.jsonl (JSON Lines format):

{"deployment_id":"dep-20260216-143022-a1b2c3","version":"1.2.3","environment":"prod","status":"success","url":"https://bio-qms-docs-abc123-uc.a.run.app","deployed_at":"2026-02-16T14:32:45Z","duration":134.1,"git_commit":"a1b2c3d4e5f6","deployer":"user@example.com"}
{"deployment_id":"dep-20260215-183045-b2c3d4","version":"1.2.2","environment":"prod","status":"success","url":"https://bio-qms-docs-abc123-uc.a.run.app","deployed_at":"2026-02-15T18:30:45Z","duration":128.7,"git_commit":"b2c3d4e5f6a1","deployer":"user@example.com"}
{"deployment_id":"dep-20260214-091234-c3d4e5","version":"1.2.1","environment":"staging","status":"success","url":"https://bio-qms-docs-staging-xyz789-uc.a.run.app","deployed_at":"2026-02-14T09:12:34Z","duration":112.3,"git_commit":"c3d4e5f6a1b2","deployer":"ci-bot@example.com"}

View Deployment History

npm run publish -- --history [--limit 10] [--env prod]

Deployment History (last 10 production deployments):

┌─────────────────────┬─────────┬─────────┬──────────┬─────────────────────────┐
│ Deployment ID       │ Version │ Status  │ Duration │ Deployed At             │
├─────────────────────┼─────────┼─────────┼──────────┼─────────────────────────┤
│ dep-20260216-143022 │ 1.2.3   │ success │ 134.1s   │ 2026-02-16T14:32:45Z    │
│ dep-20260215-183045 │ 1.2.2   │ success │ 128.7s   │ 2026-02-15T18:30:45Z    │
│ dep-20260214-091234 │ 1.2.1   │ success │ 112.3s   │ 2026-02-14T09:12:34Z    │
│ dep-20260213-163521 │ 1.2.0   │ success │ 145.8s   │ 2026-02-13T16:35:21Z    │
│ dep-20260212-145032 │ 1.1.9   │ failed  │ 67.2s    │ 2026-02-12T14:50:32Z    │
└─────────────────────┴─────────┴─────────┴──────────┴─────────────────────────┘

Success Rate: 80% (4/5)
Average Duration: 122.1s

Deployment Details

npm run publish -- --show-deployment dep-20260216-143022

Deployment Details:
  ID:           dep-20260216-143022-a1b2c3
  Version:      v1.2.3-prod
  Environment:  production
  Status:       success
  URL:          https://bio-qms-docs-abc123-uc.a.run.app
  Deployed At:  2026-02-16T14:32:45Z
  Duration:     134.1s

  Git Info:
    Branch:     main
    Commit:     a1b2c3d4e5f6
    Author:     user@example.com
    Message:    feat: Add API reference documentation

  Stages:
    Pre-flight:  PASS (2.3s)
    Validate:    PASS (3.8s)
    Build:       PASS (18.7s)
    Test:        PASS (12.4s, 2 warnings)
    Deploy:      PASS (87.6s)
    Verify:      PASS (8.9s)

  Changes:
    Documents Updated:  14
    Documents Added:    3
    Documents Removed:  1
    Size Change:        +0.12 MB

  Cloud Run:
    Service:     bio-qms-docs
    Region:      us-central1
    Revision:    bio-qms-docs-v123-prod-20260216-143022
    Image:       us-central1-docker.pkg.dev/.../docs:v1.2.3-prod
    Digest:      sha256:9f8e7d6c5b4a3...

  Logs:         .deployment/logs/dep-20260216-143022.log
  Manifest:     .deployment/manifests/dep-20260216-143022.json

---

CODITECT Framework Integration

/docs-deploy Command

The CODITECT framework provides a unified deployment command across all documentation platforms:

/docs-deploy --project bio-qms [OPTIONS]

Command Specification

Location: ~/.coditect/commands/docs-deploy.md

Implementation:

#!/usr/bin/env bash
# CODITECT Unified Documentation Deployment Command

set -euo pipefail

PROJECT="$1"
shift  # Remove project arg, pass remaining to project's publish script

case "$PROJECT" in
  bio-qms)
    cd ~/PROJECTS/coditect-rollout-master/submodules/dev/coditect-biosciences-qms-platform
    npm run publish -- "$@"
    ;;

  pilot)
    cd ~/PROJECTS/coditect-rollout-master/docs
    ./scripts/publish.sh "$@"
    ;;

  *)
    echo "Unknown project: $PROJECT"
    exit 1
    ;;
esac

Multi-Project Orchestration

Deploy multiple documentation sites in sequence:

/docs-deploy --multi bio-qms,pilot --env staging

=== Multi-Project Deployment ===

Projects: bio-qms, pilot
Environment: staging
Strategy: sequential

[1/2] Deploying bio-qms...
✓ bio-qms deployed successfully (v1.2.3-staging, 134.1s)

[2/2] Deploying pilot...
✓ pilot deployed successfully (v2.0.1-staging, 87.3s)

═══════════════════════════════════════════════
✓ MULTI-DEPLOYMENT SUCCESSFUL

Projects Deployed: 2/2
Total Duration:    221.4s

URLs:
  bio-qms: https://bio-qms-docs-staging-abc123.run.app
  pilot:   https://pilot-docs-staging-xyz789.run.app
═══════════════════════════════════════════════

Framework Integration Points

Integration	Purpose
Session Logging	All deployments logged to ~/.coditect-data/session-logs/
Context Database	Deployment history stored in org.db
Notification System	Deployments trigger framework notification hooks
Task Tracking	Deployments linked to TRACK tasks (e.g., A.4.8)
Experience Packs	Deployment patterns captured for reuse

Notification Integration

# Framework automatically notifies on deployment events
/docs-deploy --project bio-qms --env prod

# Triggers:
# 1. Session log entry
# 2. Slack notification (if configured)
# 3. Email alert (if configured)
# 4. Webhook POST (if configured)

---

Notification Hooks

Slack Integration

Configure Slack webhook in .env:

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX

Deployment Success Notification:

POST https://hooks.slack.com/services/...
{
  "text": "BIO-QMS Docs deployed to production",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "✓ *BIO-QMS Docs Deployed to Production*\n\n*Version:* `v1.2.3-prod`\n*URL:* https://bio-qms-docs-abc123.run.app\n*Deployer:* user@example.com\n*Duration:* 134.1s"
      }
    },
    {
      "type": "section",
      "fields": [
        {
          "type": "mrkdwn",
          "text": "*Changes:*\n14 documents updated\n3 documents added\n1 document removed"
        },
        {
          "type": "mrkdwn",
          "text": "*Build:*\nSize: 1.89 MB\nTests: ✓ Passed"
        }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "View Docs" },
          "url": "https://bio-qms-docs-abc123.run.app"
        },
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "Rollback" },
          "value": "rollback_v1.2.3",
          "style": "danger"
        }
      ]
    }
  ]
}

Deployment Failure Notification:

{
  "text": "BIO-QMS Docs deployment failed",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "✗ *BIO-QMS Docs Deployment Failed*\n\n*Stage:* Test\n*Error:* 3 broken links detected\n*Deployer:* user@example.com\n*Duration:* 37.2s (failed)"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Broken Links:*\n• `docs/architecture/system-design.md` → `/docs/reference/api-spec.md`\n• `docs/compliance/hipaa-controls.md` → `/docs/security/encryption.md`\n• `docs/operations/runbook.md` → `/dashboards/metrics`"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Fix broken links and retry deployment. Logs: `.deployment/logs/failed-dep-20260216-143022.log`"
        }
      ]
    }
  ]
}

Email Notifications

Configure SMTP settings in .env:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=alerts@example.com
SMTP_PASS=app-specific-password
ALERT_EMAIL=team@example.com

Email Template (HTML):

<!DOCTYPE html>
<html>
<head>
  <style>
    body { font-family: Arial, sans-serif; }
    .header { background: #4CAF50; color: white; padding: 20px; }
    .content { padding: 20px; }
    .success { color: #4CAF50; }
    .error { color: #f44336; }
  </style>
</head>
<body>
  <div class="header">
    <h1>BIO-QMS Docs Deployment</h1>
  </div>
  <div class="content">
    <h2 class="success">✓ Deployment Successful</h2>
    <p><strong>Version:</strong> v1.2.3-prod</p>
    <p><strong>Environment:</strong> production</p>
    <p><strong>URL:</strong> <a href="https://bio-qms-docs-abc123.run.app">https://bio-qms-docs-abc123.run.app</a></p>
    <p><strong>Deployed:</strong> 2026-02-16T14:32:45Z</p>
    <p><strong>Duration:</strong> 134.1s</p>

    <h3>Changes</h3>
    <ul>
      <li>14 documents updated</li>
      <li>3 documents added</li>
      <li>1 document removed</li>
    </ul>

    <h3>Validation</h3>
    <ul>
      <li>✓ Pre-flight: PASS</li>
      <li>✓ Manifest: PASS</li>
      <li>✓ Build: PASS</li>
      <li>✓ Test: PASS (2 warnings)</li>
      <li>✓ Deploy: PASS</li>
      <li>✓ Verify: PASS</li>
    </ul>
  </div>
</body>
</html>

Webhook Integration

Configure custom webhook in .env:

DEPLOYMENT_WEBHOOK_URL=https://api.example.com/deployments/webhook
DEPLOYMENT_WEBHOOK_SECRET=your-webhook-secret

Webhook Payload:

POST https://api.example.com/deployments/webhook
Headers:
  Content-Type: application/json
  X-Webhook-Signature: sha256=<hmac-signature>

{
  "event": "deployment.success",
  "timestamp": "2026-02-16T14:32:45Z",
  "project": "bio-qms",
  "version": "1.2.3",
  "environment": "prod",
  "deployment_id": "dep-20260216-143022-a1b2c3",
  "url": "https://bio-qms-docs-abc123.run.app",
  "duration_seconds": 134.1,
  "deployer": "user@example.com",
  "git": {
    "branch": "main",
    "commit": "a1b2c3d4e5f6",
    "message": "feat: Add API reference documentation"
  },
  "changes": {
    "documents_updated": 14,
    "documents_added": 3,
    "documents_removed": 1
  }
}

---

Authentication and Authorization

Required GCP Permissions

IAM Roles needed for deployment:

Role	Purpose
roles/run.admin	Deploy Cloud Run services
roles/iam.serviceAccountUser	Use Cloud Run service account
roles/artifactregistry.writer	Push container images
roles/cloudbuild.builds.builder	Build containers (if using Cloud Build)
roles/logging.viewer	Read deployment logs

Service Account Setup

For CI/CD (recommended):

# Create service account
gcloud iam service-accounts create bio-qms-deployer \
  --display-name="BIO-QMS Docs Deployer"

# Grant required roles
for role in run.admin iam.serviceAccountUser artifactregistry.writer; do
  gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
    --member="serviceAccount:bio-qms-deployer@$GCP_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/$role"
done

# Create and download key
gcloud iam service-accounts keys create sa-key.json \
  --iam-account=bio-qms-deployer@$GCP_PROJECT_ID.iam.gserviceaccount.com

For local development:

# Authenticate with user account
gcloud auth login
gcloud auth application-default login

# Set project
gcloud config set project $GCP_PROJECT_ID

Environment-Specific Permissions

Environment	Who Can Deploy	Approval Required
Development	All developers	No
Staging	Senior developers, DevOps	No
Production	DevOps team only	Yes (via approval workflow)

Audit Trail

All deployments are logged with:

• Deployer identity (email)
• Timestamp
• Git commit hash
• Environment
• Success/failure status

Query audit trail:

# From deployment history
jq 'select(.environment=="prod") | {deployed_at, deployer, version, status}' \
  .deployment/history.jsonl

# From GCP Cloud Run
gcloud run revisions list \
  --service=bio-qms-docs \
  --region=us-central1 \
  --format="table(metadata.name,metadata.creationTimestamp,metadata.annotations.'run.googleapis.com/deployer')"

---

Multi-Project Support

Configuration File

Define multiple projects in .deployment/projects.json:

{
  "projects": [
    {
      "id": "bio-qms",
      "name": "BIO-QMS Documentation",
      "path": "~/PROJECTS/coditect-rollout-master/submodules/dev/coditect-biosciences-qms-platform",
      "environments": {
        "dev": {
          "gcp_project": "coditect-bio-qms-dev",
          "service": "bio-qms-docs",
          "region": "us-central1",
          "url": "https://bio-qms-docs-dev.example.com"
        },
        "staging": {
          "gcp_project": "coditect-bio-qms-staging",
          "service": "bio-qms-docs",
          "region": "us-central1",
          "url": "https://bio-qms-docs-staging.example.com"
        },
        "prod": {
          "gcp_project": "coditect-bio-qms-prod",
          "service": "bio-qms-docs",
          "region": "us-central1",
          "url": "https://docs.bio-qms.example.com"
        }
      }
    },
    {
      "id": "pilot",
      "name": "CODITECT Pilot Documentation",
      "path": "~/PROJECTS/coditect-rollout-master/docs",
      "environments": {
        "dev": { "...": "..." },
        "staging": { "...": "..." },
        "prod": { "...": "..." }
      }
    }
  ]
}

Multi-Project Deployment

npm run publish -- --multi bio-qms,pilot --env staging --yes --json

Execution:

1. Sequential: Deploy projects one-by-one (default)
2. Parallel: Deploy all projects simultaneously (--parallel)
3. Dry-Run: Preview all deployments without executing (--dry-run)

Output:

{
  "status": "success",
  "total_projects": 2,
  "successful": 2,
  "failed": 0,
  "total_duration": 221.4,
  "deployments": [
    {
      "project": "bio-qms",
      "status": "success",
      "version": "1.2.3",
      "url": "https://bio-qms-docs-staging.example.com",
      "duration": 134.1
    },
    {
      "project": "pilot",
      "status": "success",
      "version": "2.0.1",
      "url": "https://pilot-docs-staging.example.com",
      "duration": 87.3
    }
  ]
}

Parallel Deployment

npm run publish -- --multi bio-qms,pilot --env staging --parallel

=== Multi-Project Deployment (Parallel) ===

[bio-qms] Stage 1: Pre-flight... ✓
[pilot]   Stage 1: Pre-flight... ✓

[bio-qms] Stage 2: Validate... ✓
[pilot]   Stage 2: Validate... ✓

[bio-qms] Stage 3: Build... ✓
[pilot]   Stage 3: Build... ✓

[bio-qms] Stage 4: Test... ✓
[pilot]   Stage 4: Test... ✓

[bio-qms] Stage 5: Deploy... ✓
[pilot]   Stage 5: Deploy... ✓

[bio-qms] Stage 6: Verify... ✓
[pilot]   Stage 6: Verify... ✓

✓ All projects deployed successfully (139.2s)

---

Caching and Optimization

Build Cache

Vite Build Cache:

# Cache location
.vite-cache/

# Cache behavior
- Dependencies cached after first build
- Incremental rebuilds for changed files only
- Cache invalidated on package.json changes

Docker Layer Cache:

# Optimized Dockerfile with layer caching
FROM node:18-alpine AS builder
WORKDIR /app

# Cache dependencies (changes infrequently)
COPY package*.json ./
RUN npm ci --production=false

# Copy source (changes frequently)
COPY . .
RUN npm run build

Cloud Build Cache:

# cloudbuild.yaml
options:
  machineType: 'E2_HIGHCPU_8'
  diskSizeGb: 100
  cacheFrom:
    - 'us-central1-docker.pkg.dev/$PROJECT_ID/bio-qms/docs:latest'

Skip Build If Unchanged

# Calculate content hash
CURRENT_HASH=$(find docs/ research/ internal/ -type f -name "*.md" | \
  sort | xargs md5sum | md5sum | cut -d' ' -f1)

# Compare with previous deployment
PREVIOUS_HASH=$(jq -r '.content_hash' .deployment/manifests/latest.json)

if [ "$CURRENT_HASH" = "$PREVIOUS_HASH" ]; then
  echo "No content changes detected. Skipping build."
  exit 0
fi

Incremental Deploy

Only deploy changed assets:

# Compare dist/ with deployed version
CHANGED_FILES=$(diff -r dist/ .deployment/previous-build/ | grep "^Only in dist/" | wc -l)

if [ "$CHANGED_FILES" -eq 0 ]; then
  echo "No asset changes detected. Skipping deploy."
  exit 0
fi

Optimization Strategies

Strategy	Benefit	Implementation
Dependency Pre-Warming	Faster CI/CD	Cache node_modules/ in CI
Docker Layer Reuse	Faster container builds	Multi-stage Dockerfile with cached layers
Incremental Builds	Skip unchanged files	Vite incremental mode
Content Hash Check	Skip redundant deploys	Compare source content hashes
Parallel Testing	Faster test execution	Run test suites concurrently
CDN Edge Caching	Faster end-user load	CloudFlare caching rules

---

Troubleshooting Guide

Problem: Deployment Stuck

Symptoms: Deployment hangs at Stage 5 (Deploy)

Diagnosis:

# Check Cloud Run deployment status
gcloud run services describe bio-qms-docs \
  --region=us-central1 \
  --format=yaml | grep -A 10 "status"

# Check recent logs
gcloud run logs read --service=bio-qms-docs --limit=50

Resolution:

1. Wait for timeout (10 minutes default)
2. Cancel deployment: Ctrl+C
3. Automatic rollback will trigger
4. Check logs for root cause
5. Retry with --verbose for debugging

---

Problem: Build Size Budget Exceeded

Symptoms: Stage 3 (Build) fails with size budget error

Diagnosis:

# Analyze bundle size
npm run build -- --analyze

# Identify large assets
du -sh dist/**/* | sort -h | tail -20

Resolution:

# Code-split large vendor bundles
vite.config.js:
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom'],
          'vendor-ui': ['lucide-react'],
          'vendor-markdown': ['unified', 'rehype-*', 'remark-*']
        }
      }
    }
  }

# Optimize images
npm install --save-dev @squoosh/cli
npx @squoosh/cli --webp docs/**/*.{png,jpg,jpeg}

# Dynamic imports for routes
const Dashboard = lazy(() => import('./Dashboard'));

---

Problem: Broken Links After Deploy

Symptoms: Stage 4 (Test) or Stage 6 (Verify) reports broken links

Diagnosis:

# Run link checker locally
npm run test:links

# Check specific link
curl -I https://bio-qms-docs-abc123.run.app/docs/missing-page

Resolution:

1. Fix broken links in source documents
2. Update internal references
3. Add redirects for moved pages (.deployment/redirects.json)
4. Re-run validation: npm run test:links

---

Problem: GCP Authentication Failed

Symptoms: Stage 1 (Pre-flight) fails with auth error

Diagnosis:

# Check auth status
gcloud auth list
gcloud config get-value project

# Check credentials
gcloud auth application-default print-access-token

Resolution:

# For local development
gcloud auth login
gcloud auth application-default login

# For CI/CD
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
gcloud auth activate-service-account --key-file=$GOOGLE_APPLICATION_CREDENTIALS

---

Problem: Health Checks Failing

Symptoms: Stage 5 (Deploy) completes but Stage 6 (Verify) fails

Diagnosis:

# Check Cloud Run logs
gcloud run logs read --service=bio-qms-docs --limit=100

# Test health endpoint locally
docker run -p 8080:8080 <image>
curl http://localhost:8080/health

Resolution:

1. Verify health endpoint exists and returns 200 OK
2. Check container startup logs for errors
3. Increase health check timeout in Cloud Run config
4. Test container locally before deploying

---

Problem: Rollback Not Working

Symptoms: Rollback command fails or times out

Diagnosis:

# List available revisions
gcloud run revisions list \
  --service=bio-qms-docs \
  --region=us-central1

# Check revision status
gcloud run revisions describe <revision-id> \
  --region=us-central1

Resolution:

1. Verify target revision exists and is in READY state
2. If revision is RETIRED, redeploy from that version
3. Check IAM permissions for traffic migration
4. Manual rollback via Cloud Console if CLI fails

---

Problem: Slow Deployment

Symptoms: Deployment takes >5 minutes

Diagnosis:

# Profile deployment stages
npm run publish -- --env dev --verbose | grep "Stage .* PASS"

# Identify bottleneck

Optimizations:

# Cache dependencies
npm ci --cache .npm-cache

# Use faster Docker builds
DOCKER_BUILDKIT=1 docker build ...

# Parallel test execution
npm test -- --maxWorkers=4

# Skip tests in dev
npm run publish -- --env dev --skip-tests

---

Package.json Scripts

Complete package.json scripts section for BIO-QMS:

{
  "name": "coditect-biosciences-qms-platform",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite --open",
    "build": "node scripts/generate-publish-manifest.js && vite build",
    "preview": "vite preview",

    "generate-manifest": "node scripts/generate-publish-manifest.js",
    "generate-dashboard-data": "node scripts/generate-project-dashboard-data.js",

    "test": "npm run test:smoke && npm run test:accessibility && npm run test:links",
    "test:smoke": "node tests/smoke-test.js",
    "test:accessibility": "node tests/accessibility-test.js",
    "test:links": "node tests/broken-links-test.js",

    "publish": "bash scripts/publish.sh",
    "publish:dev": "npm run publish -- --env dev",
    "publish:staging": "npm run publish -- --env staging",
    "publish:prod": "npm run publish -- --env prod",
    "publish:dry-run": "npm run publish -- --dry-run",

    "rollback": "npm run publish -- --rollback latest",
    "rollback:previous": "npm run publish -- --rollback previous",

    "deployment:history": "npm run publish -- --history",
    "deployment:show": "npm run publish -- --show-deployment",
    "deployment:list-revisions": "npm run publish -- --list-revisions",

    "check-readiness": "bash scripts/check-doc-readiness.sh",
    "check-readiness:all": "bash scripts/check-doc-readiness.sh all",
    "check-readiness:sprint": "bash scripts/check-doc-readiness.sh",

    "docker:build": "docker build -t bio-qms-docs .",
    "docker:run": "docker run -p 8080:8080 bio-qms-docs",
    "docker:test": "npm run docker:build && npm run docker:run",

    "clean": "rm -rf dist/ .vite-cache/ node_modules/.vite/",
    "clean:all": "npm run clean && rm -rf node_modules/"
  }
}

---

Implementation Notes

Script Location

scripts/
├── publish.sh                          # Main orchestration script
├── lib/
│   ├── preflight.sh                   # Stage 1: Pre-flight validation
│   ├── validate.sh                    # Stage 2: Manifest validation
│   ├── build.sh                       # Stage 3: Build
│   ├── test.sh                        # Stage 4: Test
│   ├── deploy.sh                      # Stage 5: Deploy
│   ├── verify.sh                      # Stage 6: Verify
│   ├── rollback.sh                    # Rollback functionality
│   ├── version.sh                     # Version management
│   └── notify.sh                      # Notification hooks
├── generate-publish-manifest.js       # Manifest generation
├── generate-project-dashboard-data.js # Dashboard data generation
└── check-doc-readiness.sh             # Document readiness checker

Configuration Files

.deployment/
├── config.json                        # Deployment configuration
├── projects.json                      # Multi-project definitions
├── history.jsonl                      # Deployment history log
├── manifests/                         # Deployment manifests
│   ├── latest.json
│   ├── dep-20260216-143022.json
│   └── ...
└── logs/                              # Deployment logs
    ├── dep-20260216-143022.log
    ├── failed-dep-20260216-140512.log
    └── ...

Environment Variables

# GCP Configuration
GCP_PROJECT_ID=coditect-bio-qms-prod
GCP_REGION=us-central1
CLOUD_RUN_SERVICE=bio-qms-docs
ARTIFACT_REGISTRY=us-central1-docker.pkg.dev/coditect-bio-qms-prod/bio-qms

# Notification Configuration
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=alerts@example.com
SMTP_PASS=app-specific-password
ALERT_EMAIL=team@example.com
DEPLOYMENT_WEBHOOK_URL=https://api.example.com/deployments/webhook

# Build Configuration
SIZE_BUDGET_MB=5
VITE_BUILD_TIMEOUT=300

# Deployment Configuration
DEPLOYMENT_TIMEOUT=600
HEALTH_CHECK_TIMEOUT=120
ROLLBACK_ON_FAILURE=true

Testing the CLI

# Unit tests for individual stages
npm run test:unit -- scripts/lib/preflight.sh
npm run test:unit -- scripts/lib/validate.sh

# Integration tests
npm run test:integration -- --env dev

# End-to-end tests
npm run test:e2e -- --env staging

# Dry-run full deployment
npm run publish:dry-run -- --env prod --verbose

Future Enhancements

1. Preview Deployments: Temporary URLs for PR reviews
2. Blue-Green Deployments: Zero-downtime with instant rollback
3. Canary Releases: Gradual traffic shift (10% → 50% → 100%)
4. Automated Performance Testing: Lighthouse CI integration
5. Security Scanning: Container vulnerability scanning
6. Cost Tracking: Deployment cost attribution
7. Analytics Integration: Deployment impact on usage metrics
8. Approval Workflows: Multi-stage approval for production
9. Scheduled Deployments: Cron-based deployment windows
10. Multi-Region Deployments: Global CDN edge deployment

---

Conclusion

The BIO-QMS publish CLI command provides a comprehensive, automated, and safe deployment solution for regulated SaaS documentation. With six validation stages, automatic rollback, and extensive monitoring, it ensures high-quality deployments while maintaining regulatory compliance and audit trails.

Key Takeaways:

• One-click deployment from code to production
• Multiple validation gates ensure quality and compliance
• Automatic rollback on failure prevents production issues
• Comprehensive logging provides full audit trail
• CI/CD ready with JSON output and exit codes
• Multi-project support enables platform-wide deployments

Next Steps:

1. Implement scripts/publish.sh orchestration script (Task A.4.9)
2. Create individual stage scripts in scripts/lib/ (Task A.4.10-A.4.15)
3. Set up GCP Cloud Run service configuration (Task A.5)
4. Configure notification hooks (Task A.6)
5. Implement deployment dashboard (Task A.7)

---

Document Metadata:

• Version: 1.0.0
• Lines: 1,987
• Created: 2026-02-16
• Author: Claude (Sonnet 4.5)
• Task ID: A.4.8
• Track: A (Presentation & Publishing Platform)
• Status: Active
• Audience: Technical (DevOps, Developers)