fix(diagnostics): isolate test telemetry and improve cashier error reporting

[khaira777]

Problem statement

1. Test and development runs inadvertently transmitted diagnostics and telemetry under certain network configurations, polluting production telemetry in FloAdmin with synthetic development traffic.
2. In-flight order validation failures (such as insufficient inventory for specific products, variants, or add-ons) rendered generic error messages to cashiers ("Insufficient stock"), leaving staff unable to immediately identify which item or modifier blocked order completion.
3. Server error responses had the potential to leak internal exception details, stack traces, or SQL snippets into cashier toasts and user-submitted support tickets if unhandled exceptions occurred.

Root cause and evidence

1. Telemetry and cloud sync services lacked unified suppression checks for non-production environments. Although unit tests mocked or stubs were in place, runs without FLO_MATRIX_OFFLINE=1 or with partial environment setups would trigger outbound HTTP pings. Furthermore, early revisions broke offline precedence when attempting naive NODE_ENV checks.
2. The inventory service (main/services/inventory.ts) detected stock deficits but returned generic errors without product, variant, or add-on display names attached to the structured failure detail.
3. The frontend order-attempt.ts did not sanitize server errors before passing them into cashier toasts and support tickets.

Changes made

• main/services/telemetry.ts:
  • Strengthened isTelemetrySuppressed() to evaluate FLO_MATRIX_OFFLINE=1, E2E_TASK_LOCAL_PORTS, and FLO_E2E_SKIP_OPTIONAL_NETWORK=1 as strict overrides over development flags (FLO_TELEMETRY_DEV=1).
  • Added regex-based test and e2e version suppression (test, e2e, 1.0.0-test, 2.7.2-test).
  • Gated development runs (run_mode === 'dev') from production telemetry transmission by default.
• main/services/cloud-sync.ts: Blocked outgoing diagnostics flushes when isTelemetrySuppressed() is true.
• main/services/posthog-config.ts: Blocked PostHog transmission when offline or suppressed.
• main/services/inventory.ts: Enriched insufficient stock validation failures with item name, variant label, and add-on group/option names.
• frontend/src/lib/order-attempt.ts:
  • Enriched cashier error messages for structured validation failures.
  • Implemented sanitizeServerError() to bound error message lengths (max 200 chars) and reject stack traces, file paths, SQL fragments, and exception object dumps, substituting safe localized fallback messages.
• tests/helpers/test-setup.ts & tests/e2e-server.cjs: Set FLO_MATRIX_OFFLINE=1 by default to ensure all local test runs remain offline.
• Added comprehensive regression tests in tests/telemetry-leakage-prevention.test.ts (23 assertions) and frontend E2E specs in e2e/diagnostics-checkout-recovery.spec.ts.

Reproduction before the fix

• Invoking sendAnonymousDiagnosticReport() in a test environment with FLO_TELEMETRY_DEV=1 while FLO_MATRIX_OFFLINE=1 was set previously allowed transmission to proceed due to incorrect override evaluation order.
• Attempting to check out an item with insufficient stock displayed only "Insufficient stock" without identifying the offending item.

Verification after the fix

• npm run lint: 0 errors.
• npm run build: compile clean to dist/.
• npm run build:frontend: Next.js 16 export clean (27/27 static pages).
• npm run i18n:check: 24 languages clean, exact leaf parity.
• npm run docs:check: markdownlint, relative links (506 checked), and policy clean.
• npm run test:telemetry: 100% passed.
• npm run test:telemetry-leakage-prevention: 100% passed (23 assertions).
• npm run test:diagnostics-outbox-bounds: 100% passed (570 passed, 0 failed).
• npm run test:diagnostics: 100% passed.
• npm run test:issue-788-order-attempt-storage: 100% passed.
• npm run test:addon-inventory-db: 100% passed (69/69).
• npm run test:support-ticket: 100% passed (41/41).
• npm run test:script-coverage: passed (241 reachable, 298 run).
• npx playwright test e2e/diagnostics-checkout-recovery.spec.ts e2e/diagnostics-screen.spec.ts: 17 passed (18.4s).

Independent reviewer findings

• Review confirmed that isTelemetrySuppressed() properly honors offline precedence over developer overrides.
• Confirmed that restoring 2.7.2-test fixture in tests/telemetry-delivery.test.ts maintains test fixture integrity without weakening assertions.
• Confirmed that cashier error sanitization prevents sensitive technical leaks while clearly surfacing actionable stock names.

Risk assessment

• Low operational risk. Changes tighten network boundary isolation and improve UI messaging clarity. All changes are backward compatible with existing SQLite schemas and API routes.

Remaining limitations

• Telemetry suppression relies on environment flags and version string patterns; unofficial forks modifying versions without updating build flags must configure FLO_MATRIX_OFFLINE=1 to guarantee local isolation.

Related issues and PRs

• Related to FloCafe PR feat: add structured diagnostics and actionable POS failure feedback #1032 (Diagnostics v2).
• Coordinates with FloAdmin PR on feat/diagnostics-triage-hardening and flopos.com privacy disclosures.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: FreeOpenSourcePOS/FloCafe/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1ff2b040-3937-4b3a-bf3c-f8627552390a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}