@mushi-mushi/core 1.2.0 → 1.5.0

package/CONTRIBUTING.md

@@ -101,6 +101,17 @@ Releases are fully automated. Maintainers don't run `npm publish` by hand.
 
 If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
 
+### Known CI/CD quirks and their automatic safeguards
+
+A handful of GitHub-Actions × Changesets edge cases have caused release-pipeline stalls in the past. Each is now caught automatically — keep these in mind when you see the symptom:
+
+| Symptom | Root cause | Automatic safeguard |
+| --- | --- | --- |
+| The `Build & Test` required check never registers on the `chore: version packages` PR — the PR stays "Required check missing" forever | `changeset-release/master` is pushed by `github-actions[bot]`. GitHub silently drops the downstream `pull_request` event to prevent bot loops (observed on PR #45, #102, #124). | `ci.yml` now also triggers on `push` to `changeset-release/master`, so `Build & Test` reports against the head commit directly. No empty-commit nudge needed. |
+| Release workflow fails with `No commits between master and changeset-release/master` after merging a PR with a new changeset. | A `.changeset/*.md` file whose YAML frontmatter only targets packages listed in `.changeset/config.json#ignore` (e.g. `@mushi-mushi/server`, `@mushi-mushi/admin`). `changeset version` produces no bumps, the version PR is empty, the next push errors (PR #102 / #121, 2026-05-19). | `pnpm check:changeset-orphans` runs in both `ci.yml` and `release.yml`. PR CI fails with an actionable message naming the orphan file *before* it can reach master. If you legitimately need to record an internal-only change, omit the changeset entirely — the diff lives in git history. |
+| Release workflow's `Audit signatures of installed dependencies` step fails with `npm ETARGET / No matching version found for @mushi-mushi/<pkg>@<ver>` seconds after the publish step succeeded. | npm's registry CDN can take up to ~30s to propagate a freshly-published manifest. The audit step shells out to `npm install` against the just-published version and races the CDN (observed 2026-05-20, run 26149167393). | The audit step retries with exponential backoff (1, 2, 4, 8, 16, 32s — 63s total) before failing. Sigstore signatures are written at publish time, so a one-off audit failure never indicates a corrupted package — `pnpm view <pkg> version` is the ground truth. |
+| Push to `master` after merging a PR doesn't fire the `Release` workflow. | Same anti-loop protection: when a squash merge is attributed to `github-actions[bot]`, GitHub may suppress the downstream `push` trigger. Sporadic — observed twice in the last 60 days. | `release.yml` keeps `workflow_dispatch` as the manual fallback. Recovery: **Actions → Release → Run workflow → master**. The `Build & Verify` job re-runs identically to the auto-fired path. |
+
 ### Adding a brand-new publishable package
 
 Trusted Publisher bindings are configured **per package** on `npmjs.com` and require the package to already exist on the registry. New packages therefore need a one-time bootstrap before OIDC can take over.

package/dist/index.d.cts

@@ -19,6 +19,41 @@ interface MushiConfig {
     integrations?: MushiIntegrationsConfig;
     offline?: MushiOfflineConfig;
     rewards?: MushiRewardsConfig;
+    /**
+     * Sentry-spec-1.0 hook fired AFTER preFilter / on-device classifier /
+     * rate-limit gates pass and BEFORE the report is sent or queued.
+     * Return:
+     *   - the report (possibly modified) → submit as-is
+     *   - a Promise<MushiReport> → await, then submit
+     *   - `null` → drop the report silently (no `report:sent`/`:failed` event)
+     *
+     * Use this for app-level redaction of sensitive metadata, hard-coded
+     * tag overrides, or last-mile category routing. Errors thrown inside
+     * the hook are caught and logged; the report still ships unchanged so
+     * a buggy hook never silently swallows feedback.
+     *
+     * Mirrors Sentry's [SDK feedback spec §4](https://develop.sentry.dev/sdk/telemetry/feedbacks/)
+     * `beforeSendFeedback` callback.
+     */
+    beforeSendFeedback?: (report: MushiReport) => MushiReport | Promise<MushiReport | null> | null;
+    /**
+     * Sentry-spec-1.0 callback fired exactly once on `init()` after the
+     * SDK detects that the previous browser session ended in a crash
+     * (uncaught exception, unhandled rejection, or hard navigate during
+     * unfinished submit). Use it to surface a "Tell us what went wrong?"
+     * prompt to the user — the SDK does NOT auto-open the widget so the
+     * host app can decide on copy and timing.
+     *
+     * The promise resolves with `true` when a crash was detected, `false`
+     * when the previous run ended cleanly, and `null` when the SDK can't
+     * tell (typically: localStorage unavailable, or first-ever load).
+     *
+     * Mirrors Sentry's [SDK feedback spec §6](https://develop.sentry.dev/sdk/telemetry/feedbacks/)
+     * `onCrashedLastRun` hook.
+     */
+    onCrashedLastRun?: (info: {
+        crashed: boolean | null;
+    }) => void;
     debug?: boolean;
     enabled?: boolean;
 }
@@ -73,6 +108,13 @@ interface MushiWidgetConfig {
      * actively inviting feedback.
      */
     betaMode?: MushiBetaModeConfig;
+    /**
+     * Minimum description length (characters) required before the user can submit.
+     * Overrides the SDK default of 20. The widget halves this automatically for
+     * CJK locales (ja/zh/ko) where a short string carries more semantic content
+     * than in English. Forwarded from `preFilter.minDescriptionLength` if unset.
+     */
+    minDescriptionLength?: number;
 }
 interface MushiBetaModeConfig {
     enabled?: boolean;
@@ -662,7 +704,30 @@ interface MushiPerformanceMetrics {
     lcp?: number;
     cls?: number;
     fid?: number;
+    /**
+     * Interaction to Next Paint — the worst-observed user interaction
+     * latency (ms) since SDK init. Replaces FID as a Core Web Vital
+     * since March 2024. Captured via `PerformanceObserver({ type: 'event',
+     * durationThreshold: 40 })` per the [web-vitals INP spec](https://web.dev/articles/inp).
+     */
     inp?: number;
+    /**
+     * Optional INP attribution — captured from the worst-observed
+     * interaction. Lets the triage UI surface "the slow click was on
+     * <button.checkout>" rather than just "1200 ms INP".
+     */
+    inpAttribution?: {
+        /** PerformanceEventTiming.name (`pointerdown`, `keydown`, …). */
+        eventType?: string;
+        /** Tag + id + first class of the element that triggered the slow event. */
+        targetSelector?: string;
+        /** Time between the user input and the start of event processing. */
+        inputDelay?: number;
+        /** Time spent running the event handler. */
+        processingDuration?: number;
+        /** Time between handler end and the next paint. */
+        presentationDelay?: number;
+    };
     ttfb?: number;
     longTasks?: number;
 }
@@ -697,7 +762,14 @@ interface MushiTimelineEntry {
     kind: MushiTimelineKind;
     payload: Record<string, unknown>;
 }
-type MushiEventType = 'report:submitted' | 'report:queued' | 'report:sent' | 'report:failed' | 'widget:opened' | 'widget:closed' | 'proactive:triggered' | 'proactive:dismissed';
+type MushiEventType = 'report:submitted' | 'report:queued' | 'report:sent' | 'report:failed'
+/**
+ * Fired when the submitted report has been picked up by a Cursor Cloud
+ * Agent and an automated fix is in progress. `data.agentId` is the
+ * Cursor agent run ID (bc-…); `data.fixId` is the mushi fix_attempt UUID.
+ * Useful for showing a toast: "A Cursor agent is working on your report".
+ */
+ | 'report:dispatched' | 'widget:opened' | 'widget:closed' | 'proactive:triggered' | 'proactive:dismissed';
 type MushiEventHandler = (event: {
     type: MushiEventType;
     data?: unknown;

package/dist/index.d.ts

@@ -19,6 +19,41 @@ interface MushiConfig {
     integrations?: MushiIntegrationsConfig;
     offline?: MushiOfflineConfig;
     rewards?: MushiRewardsConfig;
+    /**
+     * Sentry-spec-1.0 hook fired AFTER preFilter / on-device classifier /
+     * rate-limit gates pass and BEFORE the report is sent or queued.
+     * Return:
+     *   - the report (possibly modified) → submit as-is
+     *   - a Promise<MushiReport> → await, then submit
+     *   - `null` → drop the report silently (no `report:sent`/`:failed` event)
+     *
+     * Use this for app-level redaction of sensitive metadata, hard-coded
+     * tag overrides, or last-mile category routing. Errors thrown inside
+     * the hook are caught and logged; the report still ships unchanged so
+     * a buggy hook never silently swallows feedback.
+     *
+     * Mirrors Sentry's [SDK feedback spec §4](https://develop.sentry.dev/sdk/telemetry/feedbacks/)
+     * `beforeSendFeedback` callback.
+     */
+    beforeSendFeedback?: (report: MushiReport) => MushiReport | Promise<MushiReport | null> | null;
+    /**
+     * Sentry-spec-1.0 callback fired exactly once on `init()` after the
+     * SDK detects that the previous browser session ended in a crash
+     * (uncaught exception, unhandled rejection, or hard navigate during
+     * unfinished submit). Use it to surface a "Tell us what went wrong?"
+     * prompt to the user — the SDK does NOT auto-open the widget so the
+     * host app can decide on copy and timing.
+     *
+     * The promise resolves with `true` when a crash was detected, `false`
+     * when the previous run ended cleanly, and `null` when the SDK can't
+     * tell (typically: localStorage unavailable, or first-ever load).
+     *
+     * Mirrors Sentry's [SDK feedback spec §6](https://develop.sentry.dev/sdk/telemetry/feedbacks/)
+     * `onCrashedLastRun` hook.
+     */
+    onCrashedLastRun?: (info: {
+        crashed: boolean | null;
+    }) => void;
     debug?: boolean;
     enabled?: boolean;
 }
@@ -73,6 +108,13 @@ interface MushiWidgetConfig {
      * actively inviting feedback.
      */
     betaMode?: MushiBetaModeConfig;
+    /**
+     * Minimum description length (characters) required before the user can submit.
+     * Overrides the SDK default of 20. The widget halves this automatically for
+     * CJK locales (ja/zh/ko) where a short string carries more semantic content
+     * than in English. Forwarded from `preFilter.minDescriptionLength` if unset.
+     */
+    minDescriptionLength?: number;
 }
 interface MushiBetaModeConfig {
     enabled?: boolean;
@@ -662,7 +704,30 @@ interface MushiPerformanceMetrics {
     lcp?: number;
     cls?: number;
     fid?: number;
+    /**
+     * Interaction to Next Paint — the worst-observed user interaction
+     * latency (ms) since SDK init. Replaces FID as a Core Web Vital
+     * since March 2024. Captured via `PerformanceObserver({ type: 'event',
+     * durationThreshold: 40 })` per the [web-vitals INP spec](https://web.dev/articles/inp).
+     */
     inp?: number;
+    /**
+     * Optional INP attribution — captured from the worst-observed
+     * interaction. Lets the triage UI surface "the slow click was on
+     * <button.checkout>" rather than just "1200 ms INP".
+     */
+    inpAttribution?: {
+        /** PerformanceEventTiming.name (`pointerdown`, `keydown`, …). */
+        eventType?: string;
+        /** Tag + id + first class of the element that triggered the slow event. */
+        targetSelector?: string;
+        /** Time between the user input and the start of event processing. */
+        inputDelay?: number;
+        /** Time spent running the event handler. */
+        processingDuration?: number;
+        /** Time between handler end and the next paint. */
+        presentationDelay?: number;
+    };
     ttfb?: number;
     longTasks?: number;
 }
@@ -697,7 +762,14 @@ interface MushiTimelineEntry {
     kind: MushiTimelineKind;
     payload: Record<string, unknown>;
 }
-type MushiEventType = 'report:submitted' | 'report:queued' | 'report:sent' | 'report:failed' | 'widget:opened' | 'widget:closed' | 'proactive:triggered' | 'proactive:dismissed';
+type MushiEventType = 'report:submitted' | 'report:queued' | 'report:sent' | 'report:failed'
+/**
+ * Fired when the submitted report has been picked up by a Cursor Cloud
+ * Agent and an automated fix is in progress. `data.agentId` is the
+ * Cursor agent run ID (bc-…); `data.fixId` is the mushi fix_attempt UUID.
+ * Useful for showing a toast: "A Cursor agent is working on your report".
+ */
+ | 'report:dispatched' | 'widget:opened' | 'widget:closed' | 'proactive:triggered' | 'proactive:dismissed';
 type MushiEventHandler = (event: {
     type: MushiEventType;
     data?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/core",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Core types, API client, and pre-filter for Mushi Mushi SDK",
   "license": "MIT",
   "type": "module",