SnagBadgerA little help for every snag.
DocsView Markdown source ↗

Provider and harvester onboarding review#

For each selected application, use the repository helper entry tooling/onboarding/reporting-setup.mts. Its ReportingSetupRequest.target accepts the selected-target ID from discovery or a host-owned application identifier. revision identifies the inspected implementation, configuration and public adapter options. Keep reporting and testing consumers explicit; adapt shared configuration through the supported configuration resolver.

Inspect and propose#

  1. Inspect the installed public exports, version, adapter documentation and actual host options. Load project modules only within approved scope; this helper never discovers or imports arbitrary project code. Pass an already loaded public harvester namespace to recommendInstalledHarvesters. Its available recommendations start selected for review, without starting collection.
  2. Build one request containing each consumer's real ReportingConfiguration and SessionSelection, or PluginConfiguration and PluginSelection. Compatibility IDs are registration IDs; plugin capability IDs are pluginId/capabilityId. Collection verification selects diagnostics only. Keep custom host registrations and their loader/options intact.
  3. For each required provider/harvester, add an interface record with its entry, version, documentation, nonsecret input proposals and their option sources, collected data, lifecycle, bounds, sanitization and limitations. Describe credential resolution with references only; keep credential values in their execution environment. Interface records are inspected evidence, not universal schema reflection. Inspect actual host factories: content enabled in their options belongs in content, even without editable runtime settings.
  4. Call inspectReportingSetup(request). It reads actual supported metadata and settings without invoking adapter loaders, plugin instances or tab renderers. The SDK runtime's inspect(selection) owns the same selection/settings policy used by start(selection) for both compatibility and plugin adapters; onboarding projects those results and adds its diagnostics-only scope. Every selected capability needs a requirement. Show all pending/blocked items and proposed inputs before requesting concrete-change approval.

requirements retains a requested Jira/Linear destination even when its adapter is absent. Put unavailable account/PIN policy in that requirement's pending reason. A repository remote supplies no tracker/project identity. Local output is a separate user choice. Setup never authenticates, connects accounts, loads providers or submits reports; provider connection remains unverified, including for fixture destinations. Runtime settings expose the installed boolean, bounded number and choice schemas, with developer restrictions. Project identifiers come from actual adapter options/host configuration, not invented free-text settings.

The four maintained factories are compatibility harvesters, not complete plugins. Browser diagnostics omit cookies/storage/DOM and observe popstate/hashchange, not complete navigation history. App snapshots require an explicitly approved read callback. HTTP defaults to metadata; fetch outcomes and response streams remain unavailable. WebSocket instrumentation sees newly created sockets, not existing connections or earlier messages. Inspect actual filter, sanitizer, maxEntries and maxContentBytes options; verify their effects rather than inferring privacy from an adapter's name.

Content and pre-recording each require explicit opt-in. Reporter choices narrow developer-enabled collection and editable settings. Diagnostic pre-recording is off by default; SDK/extension recording evidence and drafts remain memory-only. AI-suite retained run artifacts follow their existing separate policy. A detected library is a candidate: record pending, declined or approved per specific custom integration. Approved work needs both consent and changeApproval evidence. A general setup approval supplies neither implicitly.

Verify approved collection#

Call verifyReportingSetup(request, approval, hosts) after approval. Supply {reviewId: review.id, evidence: approvalReference, disposable: true} and a ReportingVerificationHost for each consumer. The helper owns the supported collection runtime, starts only the reviewed selections, finishes evidence and disposes the runtime even if an exercise fails. Provider requirements may remain pending while independently approved collection is checked.

Approved collection owns a snapshot of request metadata and selected host callbacks before asynchronous work begins. It preserves installed callback identity, checks the live request after each asynchronous stage and at final completion, and blocks stale results across both consumers. Equivalent persisted object-key order retains identity; nonfinite metadata is rejected. Host check records are copied before later callbacks can mutate them. Approval and check results require the boolean true; a failed inactive probe prevents activation.

The disposable host supplies an inactive-state probe, actual scenario actions, an output inspector and a post-disposal probe. Return exactly one check for each of inactive, collection, bounds, sanitization, cleanup and failure-isolation, each with an observed boolean and a nonsecret evidence reference. Inspect real configured output, overflow bounds and sanitization; exercise a failed sibling and confirm the host and other collectors survive. Use the actual testing runtime/attempt when verifying testing support. The name testing alone establishes no runtime integration. Missing, failed or duplicate checks block observed status. Host probes are application-specific trusted test code, not a new core plugin contract or a security certification.

Approval identity covers the application, revision, installed function identities, settings, options evidence, selections and requirements. Re-review after changes. Function identity is process-local: re-review and bind approval in the process that performs verification. Changing closure-owned data requires a new host revision. Keep requests stable during asynchronous verification. The helper returns check summaries, not captured evidence or credentials; keep underlying records only in the approved evidence location.

For explicitly chosen local output, produce a real reviewed bundle using createReportBundle, then call verifyLocalReportingExport(bundle). It uses the canonical importReportBundle validator, including reviewed HTML and attachments. validated-local-export establishes bundle validity, not a provider connection.

Maintained checks#

After pnpm worktree:setup and pnpm build, run:

pnpm exec node --test tooling/onboarding/reporting-review.test.mts tooling/onboarding/reporting-verification.test.mts tooling/onboarding/reporting-runner.test.mts tooling/onboarding/reporting-approval.test.mts
pnpm verify
pnpm dev:examples

The direct fixtures exercise host-owned application adapters through both public compatibility and plugin runtimes and retain their evidence in a portable runner attempt. The installed browser factories need browser host types and are verified in their maintained browser consumers. The maintained /harvesters/ and /harvesters/plain.html examples exercise real fetch/XHR/WebSocket traffic, bounded/sanitized collection, custom replacement, inactive behavior and failure isolation. Observe these from the owned T3 preview with current source identity. Report configuration validity, observed collection, local bundle validity and unverified provider/account connectivity as separate results. Record unsupported requirements for user-directed recovery rather than silently replacing them.