# FieldOps Cloud Commands

Exact local commands for the PHP/XAMPP development and QA workflow.

## Working Directory

```powershell
cd 'C:\Users\chama\OneDrive\Documents\FieldOps Cloud'
```

## Local URLs

- XAMPP web app: `http://localhost/FieldOps-Cloud/public`
- Tenant demo entry: `http://localhost/FieldOps-Cloud/public/demo/company-admin`
- Platform admin demo entry: `http://localhost/FieldOps-Cloud/public/demo/platform-admin`
- Platform admin console: `http://localhost/FieldOps-Cloud/public/platform-admin`

## PHP And Composer

Use the Composer executable available on this machine:

```powershell
& 'C:\composer\composer.bat' install --no-interaction --no-progress
& 'C:\composer\composer.bat' validate --no-check-publish
& 'C:\composer\composer.bat' audit
& 'C:\composer\composer.bat' test
$env:COMPOSER_PROCESS_TIMEOUT='0'; & 'C:\composer\composer.bat' check
```

The shorter commands also work when Composer is on PATH:

```powershell
composer install --no-interaction --no-progress
composer validate --no-check-publish
composer audit
composer test
$env:COMPOSER_PROCESS_TIMEOUT='0'; composer check
```

## Static Route And Button Inventory

```powershell
php tools\qa-inventory.php
```

Output:

- `docs/QA_ROUTE_ACTION_INVENTORY.md`

This check is also part of `composer check`.

## HTTP Route Harness

```powershell
& 'C:\composer\composer.bat' http-route-harness
```

Equivalent direct command:

```powershell
php tools\http-route-harness.php
```

The HTTP route harness verifies the core dispatcher contract without a browser: GET/404/403 handling, XAMPP base-path stripping, trailing slash normalization, CSRF rejection for non-API POSTs, API POST bearer-token handling, and registration of high-risk routes. It writes `docs/HTTP_ROUTE_HARNESS_REPORT.md` and is part of `composer check` and `composer release-gate`.

## API Contract Harness

```powershell
& 'C:\composer\composer.bat' api-contract-harness
```

Equivalent direct command:

```powershell
php tools\api-contract-harness.php
```

The Gate 22 API contract harness verifies JSON response envelopes, JSON 404/403 errors for `/api/*` routes, API POST CSRF boundary behavior, disabled billing webhook JSON errors when provider secrets are absent, active API-style route registration, planned REST route absence, and API documentation truth markers. It writes `docs/API_CONTRACT_HARNESS_REPORT.md` and is part of `composer check` and `composer release-gate`.

Gate 23 report durability is covered by `composer test`. It verifies that `/reports` uses computed tenant job, quote, invoice, and team-member summaries instead of hard-coded revenue or technician-placeholder values.

Gate 24 dashboard durability is covered by `composer test`. It verifies that `/dashboard` uses tenant-backed job, quote, and invoice summaries, excludes approved quotes from the pending quote list, and no longer renders the fixed `+12% from last month` placeholder.

Gate 25 period-scoped summaries are covered by `composer test`. It verifies that `/reports` and `/dashboard` apply explicit all-time/custom period filters before rendering revenue, invoice, quote, and job summaries.

Gate 26 previous-period trends are covered by `composer test`. It verifies that comparable periods are calculated from `ReportPeriodService` and that `/reports` plus `/dashboard` render real trend/comparison text instead of placeholders.

Gate 27 advanced report summaries are covered by `composer test`. It verifies that `/reports` renders computed productivity, first-time-fix proxy, quote conversion, engineer productivity, customer performance, and profitability-readiness summaries while withholding margin reporting until cost data exists. Gate 30 adds the material-cost-backed margin foundation.

Gate 28 saved report presets are covered by `composer test`. It verifies saved report preset validation, tenant-scoped session/database persistence, `/reports` open/save/delete UI rendering, and audit events for preset creation/deletion.

Gate 29 scheduled report delivery foundation is covered by `composer test`. It verifies `manage_reports` RBAC, tenant-scoped delivery queue persistence, duplicate prevention, `/reports` delivery queue UI rendering, route registration, and audit events for queue actions while live provider delivery remains disabled until configured.

Gate 30 cost-backed profitability foundation is covered by `composer test`. It verifies material-cost-backed profitability stays unavailable without cost data, computes costed revenue/material cost/captured cost/gross profit/margin from linked invoice job inventory movements, renders cost-backed Reports UI labels, and keeps the inventory movement profitability lookup index in the schema.

Gate 31 job cost capture foundation is covered by `composer test`. It verifies tenant-scoped direct cost persistence, job cost validation, `manage_job_costs` RBAC, audit logging, job detail cost ledger rendering, demo reset coverage, direct cost profitability rollups, and the job cost lookup indexes in schema/volume checks.

Gate 32 contract profitability foundation is covered by `composer test`. It verifies maintenance-agreement/job/invoice/billing-schedule/cost rollups, `/reports` Contract Profitability rendering, and the rule that unlinked same-customer invoices are not counted as contract revenue.

Gate 33 purchase-order accrual foundation is covered by `composer test`. It verifies tenant-scoped purchase-order repositories, draft/cancelled exclusion, cross-tenant line isolation, demo reset coverage, and `/reports` purchase-order accrual rendering.

Gate 34 supplier-invoice matching foundation is covered by `composer test`. It verifies tenant-scoped supplier invoice repositories, draft supplier invoice exclusion, matched purchase-order accrual replacement, cross-tenant line isolation, demo reset coverage, schema indexes, and `/reports` supplier invoice cost rendering.

Gate 35 payroll/time-sheet import foundation is covered by `composer test`. It verifies the Timesheets / payroll import schema, mandatory payroll costing fields, row-level validation, tenant-scoped time-sheet repositories, import commit/undo through the existing durable import pipeline, draft payroll exclusion, approved labour cost rollups, schema indexes, demo reset coverage, and `/reports` timesheet labour cost rendering.

## Controller Form-Flow Harness

```powershell
& 'C:\composer\composer.bat' form-flow-harness
```

Equivalent direct command:

```powershell
php tools\form-flow-harness.php
```

The form-flow harness verifies selected high-risk POST workflows at the app/controller/repository boundary: client creation, DB-backed schedule appointment booking, CSRF no-mutation protection, confirmed platform tenant action mutation, and tenant action confirmation enforcement. It writes `docs/FORM_FLOW_HARNESS_REPORT.md` and is part of `composer check` and `composer release-gate`.

## XAMPP Sync

Apache serves the copy under `C:\xampp\htdocs\FieldOps-Cloud`. After code or template changes, sync the changed project files before browser checks:

```powershell
Copy-Item -Path 'src','templates','public','config','database','tools','docs','tests','composer.json','composer.lock','README.md','AGENTS.md','.project-status','.env.example','migrations','package.json','capacitor.config.json','mobile','.github' -Destination 'C:\xampp\htdocs\FieldOps-Cloud' -Recurse -Force
```

## XAMPP Browser Smoke

Requires XAMPP Apache running and Chrome installed.

Run browser smoke commands serially. They exercise shared demo/session state and can report transient failures if multiple Chrome smoke suites run against the same XAMPP copy at the same time.

```powershell
$env:FIELDOPS_BASE_URL='http://localhost/FieldOps-Cloud/public'
$env:BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
$env:NODE_PATH='C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules;C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules\.pnpm\node_modules'
& 'C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe' tools\browser-smoke.cjs
```

The smoke test covers public, tenant-owner, and platform-admin scenarios across mobile, tablet, and desktop viewports. It blocks service workers and serves empty test stubs for jsDelivr assets so local results are not affected by PWA cache state or CDN availability.

## XAMPP Role/RBAC Browser Walkthrough

Requires XAMPP Apache running and Chrome installed.

```powershell
$env:FIELDOPS_BASE_URL='http://localhost/FieldOps-Cloud/public'
$env:BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
$env:NODE_PATH='C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules;C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules\.pnpm\node_modules'
& 'C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe' tools\role-walkthrough.cjs
```

The role walkthrough covers Owner, Manager, Supervisor, Team Member, Trainee, read-only Demo User, Platform Admin, forbidden-route 403 checks, role-filtered navigation, and platform-admin support login-as/return flow. It uses the same isolated browser context and CDN stubs as the route smoke.

## XAMPP High-Risk Role Interaction Smoke

Requires XAMPP Apache running and Chrome installed.

```powershell
$env:FIELDOPS_BASE_URL='http://localhost/FieldOps-Cloud/public'
$env:BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
$env:NODE_PATH='C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules;C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules\.pnpm\node_modules'
& 'C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe' tools\role-interaction-smoke.cjs
```

The Gate 20 role interaction smoke checks selected live-browser actions: owner schedule time-slot selection and booking, quote billing-point add/delete UI behavior, supervisor/demo-user forbidden create routes, and owner import validation blocking invalid CSV before commit.

## XAMPP Accessibility Smoke

Requires XAMPP Apache running and Chrome installed.

```powershell
$env:FIELDOPS_BASE_URL='http://localhost/FieldOps-Cloud/public'
$env:BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
$env:NODE_PATH='C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules;C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules\.pnpm\node_modules'
& 'C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe' tools\accessibility-smoke.cjs
```

The accessibility smoke covers public, tenant-owner, and platform-admin pages on mobile and desktop. It checks document language/title, visible h1, skip link and main landmark, interactive control names, field labels, visible image alt text, and duplicate IDs. It writes `docs/ACCESSIBILITY_SMOKE_REPORT.md`.

## Performance And Large-Data Smoke

```powershell
& 'C:\composer\composer.bat' performance-smoke
```

Equivalent direct command:

```powershell
php tools\performance-smoke.php
```

The performance smoke validates 500-row CSV preview, commit, bounded list-read, and undo coverage for customers, jobs, quotes, invoices, and team imports. It also confirms the 1,000-row import limit rejects a 1,001-row file and writes `docs/PERFORMANCE_SMOKE_REPORT.md`.

## Mobile App Readiness Smoke

```powershell
& 'C:\composer\composer.bat' mobile-readiness
```

Equivalent direct command:

```powershell
php tools\mobile-readiness.php
```

The mobile readiness smoke verifies the PWA manifest, service worker, offline fallback, offline technician workflow, Capacitor package/config, and native launch shell. It intentionally reports Android/iOS project generation, signing, store metadata, privacy manifest, and physical-device QA as blocked until owner evidence variables are populated. It writes `docs/MOBILE_APP_READINESS_REPORT.md`.

## Release Gate Runner

```powershell
& 'C:\composer\composer.bat' release-gate
```

Equivalent direct command:

```powershell
php tools\release-gate.php
```

The release-gate runner executes Composer validate, Composer audit against `composer.lock`, service tests, PHP lint, route/action inventory, HTTP route harness, API contract harness, controller form-flow harness, performance smoke, mobile readiness smoke, Gate 21 service-level import payload replay assertions, Gate 23 core report durability assertions, Gate 24 dashboard durability assertions, Gate 25 period-scoped summary assertions, Gate 26 previous-period trend assertions, Gate 27 advanced report summary assertions, Gate 28 saved report preset assertions, Gate 29 scheduled report delivery foundation assertions, Gate 30 cost-backed profitability assertions, Gate 31 direct job cost capture assertions, Gate 32 contract profitability assertions, Gate 33 purchase-order accrual assertions, Gate 34 supplier-invoice matching assertions, and Gate 35 payroll/time-sheet import assertions, then writes `docs/RELEASE_GATE_REPORT.md`. Browser smokes, including the Gate 20 high-risk role interaction smoke, are optional and are skipped unless `FIELDOPS_RELEASE_GATE_BROWSER=1` is set with Node, Playwright, Chrome, and `FIELDOPS_BASE_URL` configured. Gate 36 production workflow browser smoke is a separate optional release-gate check and is skipped unless `FIELDOPS_RELEASE_GATE_PRODUCTION_WORKFLOW=1` is set with Node, Playwright, Chrome, PHP, and browser executable configuration.

The disposable MySQL tenant-isolation smoke and MySQL volume profile are also available as optional release-gate checks. They are skipped unless `FIELDOPS_RELEASE_GATE_MYSQL=1` is set with reachable MySQL credentials.

## Production Auth Smoke

Runs a temporary PHP development server in production mode with demo access disabled and a disposable SQLite database seeded with DB-backed role users.

```powershell
$env:PHP_BINARY_PATH='C:\xampp\php\php.exe'
$env:BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
$env:NODE_PATH='C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules;C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules\.pnpm\node_modules'
& 'C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe' tools\auth-production-smoke.cjs
```

The production auth/security smoke verifies `/auth`, CSP/security headers, session cookie policy, disabled demo routes, unauthenticated dashboard access, invalid login, signup, DB-backed login for Owner/Manager/Supervisor/Team Member/Trainee/Platform Admin, and platform-admin isolation. It blocks service workers and serves empty jsDelivr test stubs; the platform-admin RBAC assertion uses the authenticated browser context HTTP client to validate the same session cookie without depending on browser navigation lifecycle timing.

## Production Workflow Smoke

Runs a temporary PHP development server in production mode with demo access disabled and a disposable SQLite database seeded with DB-backed tenant roles. This is a destructive reset only inside `runtime/production-workflow-smoke`.

```powershell
$env:PHP_BINARY_PATH='C:\xampp\php\php.exe'
$env:BROWSER_EXECUTABLE_PATH='C:\Program Files\Google\Chrome\Application\chrome.exe'
$env:NODE_PATH='C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules;C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\node_modules\.pnpm\node_modules'
& 'C:\Users\chama\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe' tools\production-workflow-smoke.cjs
```

The production workflow smoke verifies DB-backed login, dashboard access, client create/search/detail/edit persistence, job create/detail/edit persistence, team member create/detail/edit persistence, quote create/search/detail/edit persistence, invoice create/search/detail/edit/payment persistence, validation failures, schedule booking, import preview/commit/undo, Basic-plan export blocking, tenant-isolation negative checks, platform-admin support login-as/return, customer portal quote approval, customer portal invoice payment validation and sandbox recording, customer portal booking requests, and production role route matrices for Owner, Manager, Supervisor, Team Member, Trainee, and Platform Admin. It blocks service workers and stubs jsDelivr assets for deterministic local browser execution.

## MySQL Health

```powershell
& 'C:\xampp\mysql\bin\mysqladmin.exe' -u root ping
& 'C:\xampp\mysql\bin\mysql.exe' --version
```

## MySQL Tenant Isolation Smoke

Requires XAMPP MySQL running with the local root account. The tool creates and drops a disposable database unless `FIELDOPS_KEEP_TEST_DB=1`.

```powershell
& 'C:\xampp\php\php.exe' tools\mysql-isolation-smoke.php
```

Optional environment variables:

```powershell
$env:FIELDOPS_MYSQL_HOST='127.0.0.1'
$env:FIELDOPS_MYSQL_PORT='3306'
$env:FIELDOPS_MYSQL_USER='root'
$env:FIELDOPS_MYSQL_PASSWORD=''
$env:FIELDOPS_KEEP_TEST_DB='1'
```

## MySQL Volume Profile

Requires XAMPP MySQL running with the local root account. The tool creates and drops a disposable database.

```powershell
& 'C:\composer\composer.bat' mysql-volume-profile
```

Equivalent direct command:

```powershell
& 'C:\xampp\php\php.exe' tools\mysql-volume-profile-tool.php
```

Optional environment variables:

```powershell
$env:FIELDOPS_MYSQL_HOST='127.0.0.1'
$env:FIELDOPS_MYSQL_PORT='3306'
$env:FIELDOPS_MYSQL_USER='root'
$env:FIELDOPS_MYSQL_PASSWORD=''
$env:FIELDOPS_MYSQL_VOLUME_CLIENTS='1000'
$env:FIELDOPS_MYSQL_VOLUME_JOBS='3000'
$env:FIELDOPS_MYSQL_VOLUME_DOCUMENTS='1000'
$env:FIELDOPS_MYSQL_VOLUME_APPOINTMENTS='700'
```

The MySQL volume profile imports `database/schema.sql`, verifies required operational indexes, seeds two tenants with production-like local volume, runs `EXPLAIN` plus timed reads for clients, dispatch/jobs, quotes, invoices, appointments, dashboard totals, and cross-tenant exclusion, and writes `docs/MYSQL_VOLUME_PROFILE_REPORT.md`.

## Disposable Database Import Check

Use a throwaway database name and drop it after checking imports. Do not run this against a live tenant database.

```powershell
$db = 'fieldops_qa_' + (Get-Date -Format 'yyyyMMddHHmmss')
& 'C:\xampp\mysql\bin\mysql.exe' -u root -e "CREATE DATABASE $db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
& 'C:\xampp\mysql\bin\mysql.exe' -u root $db -e "SOURCE C:/xampp/htdocs/FieldOps-Cloud/database/schema.sql;"
& 'C:\xampp\mysql\bin\mysql.exe' -u root $db -e "SOURCE C:/xampp/htdocs/FieldOps-Cloud/database/seed.sql;"
& 'C:\xampp\mysql\bin\mysql.exe' -u root $db -e "SELECT COUNT(*) AS tables_count FROM information_schema.tables WHERE table_schema = DATABASE(); SELECT COUNT(*) AS users_count FROM users; SELECT COUNT(*) AS tenants_count FROM tenants;"
& 'C:\xampp\mysql\bin\mysql.exe' -u root -e "DROP DATABASE $db;"
```

## Current Production Readiness Evidence

The latest full QA pass is documented in:

- `docs/PRODUCTION_READINESS_QA_REPORT.md`
- `docs/QA_ROUTE_ACTION_INVENTORY.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE7_DEPLOYMENT_HARDENING.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE8_ACCESSIBILITY.md`
- `docs/ACCESSIBILITY_SMOKE_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE9_PERFORMANCE.md`
- `docs/PERFORMANCE_SMOKE_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE10_MOBILE_APP_READINESS.md`
- `docs/MOBILE_APP_READINESS_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE11_CI_RELEASE_GATE.md`
- `docs/RELEASE_GATE_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE12_MYSQL_ISOLATION_RESTORE.md`
- `docs/MYSQL_TENANT_ISOLATION_SMOKE_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE13_HTTP_ROUTE_HARNESS.md`
- `docs/HTTP_ROUTE_HARNESS_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE22_API_CONTRACT_TRUTH.md`
- `docs/API_CONTRACT_HARNESS_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE16_FORM_FLOW_HARNESS.md`
- `docs/FORM_FLOW_HARNESS_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE17_MYSQL_VOLUME_PROFILE.md`
- `docs/MYSQL_VOLUME_PROFILE_REPORT.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE18_IMPORT_EXPORT_PERSISTENCE.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE19_IMPORT_RETRY_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE20_ROLE_INTERACTION_SMOKE.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE21_IMPORT_PAYLOAD_REPLAY.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE22_API_CONTRACT_TRUTH.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE23_REPORTS_DURABILITY.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE24_DASHBOARD_DURABILITY.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE25_PERIOD_SCOPED_SUMMARIES.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE26_PREVIOUS_PERIOD_TRENDS.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE27_ADVANCED_REPORT_SUMMARIES.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE28_SAVED_REPORT_PRESETS.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE29_SCHEDULED_REPORT_DELIVERY_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE30_COST_BACKED_PROFITABILITY_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE31_JOB_COST_CAPTURE_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE32_CONTRACT_PROFITABILITY_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE33_PURCHASE_ORDER_ACCRUAL_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE34_SUPPLIER_INVOICE_MATCHING_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE35_PAYROLL_TIMESHEET_IMPORT_FOUNDATION.md`
- `docs/MASTER_PUBLIC_RELEASE_GATE36_PRODUCTION_WORKFLOW_SMOKE.md`

## Gate 7 Deployment Readiness

Local/XAMPP mode will show deployment readiness as not configured or local-only. For a real hosted environment, populate the Gate 7 variables in `.env.example`, sign in as platform admin, then open:

```text
/platform-admin/health
```

The Deployment hardening table must show ready for production mode, debug disablement, application secret, database DSN, demo disablement, HTTPS URL, secure cookies, proxy policy, public document root, logging, backup/restore, monitoring, rollback, and CI release gate before public launch.