@devfellowship/components 3.0.0 → 3.1.0

package/dist/cli.js

@@ -47,26 +47,424 @@ import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
 import chalk2 from "chalk";
 
+// src/cli/ux-paths/lib/v1.schema.json
+var v1_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://raw.githubusercontent.com/devfellowship/dfl-ux-paths/main/schema/v1.json",
+  title: "DFL UX Paths v1",
+  description: "Versioned per-app user-flow JSON schema for migration-gap analysis and dead-code detection. Accepts schema_version 1.0.0, 1.1.0, 1.2.0 and 1.3.0 (all additive \u2014 v1.1 adds optional navigation/prereq/test_metadata fields; v1.2 adds optional source_ref (screen\u2192repo file) and screenshots[] (per platform\xD7orientation), and documents `route` as the canonical shared route nomenclature for 1:1 cross-app mapping; v1.3 adds optional source (build|spec), phases[], and phase/description on screen and flow, so the format can also describe a product that has not been built yet. Backward compatible \u2014 v1.0/v1.1/v1.2 files still validate).",
+  $comment: "schema v1.2 \u2014 additive over v1.1. New optional screen fields: source_ref { component_file, file_path_chain? } links a screen to the repo file(s) that render it (Figma-Code-Connect style); screenshots[] { platform, orientation, viewport?, url, captured_at? } captures rendered images per platform\xD7orientation for vision-first comparison. `screen.id` is the STICKY 1:1 JOIN KEY across apps \u2014 comparators pair screens by shared id. `route` is the canonical shared route nomenclature (e.g. studio/project/:id/editor) letting two apps map 1:1 by the same name even when their real URLs differ. Draft 2020-12. The file `$id` is intentionally unchanged across additive bumps so consumers pinned to the canonical URL keep working. || schema v1.3 \u2014 additive over v1.2, and the first bump aimed at files authored BEFORE the code exists. `source: \"spec\"` says so explicitly: routes are proposed nomenclature, app_version carries the zero-sha `init` emits, and the absence of source_ref/screenshots/base_url is correct rather than incomplete. `phases[]` declares the app's delivery-phase vocabulary once; `screen.phase` / `flow.phase` reference a phase id. That pair is what lets a viewer render committed scope differently from work the requirement explicitly parks (`phases[].optional: true`) instead of showing one undifferentiated blob \u2014 the distinction a client reads as 'what am I actually getting'. `screen.description` / `flow.description` carry the prose a spec needs and a generated-from-code file usually does not.",
+  type: "object",
+  required: ["schema_version", "app_id", "app_version", "screens", "flows"],
+  additionalProperties: false,
+  properties: {
+    schema_version: {
+      type: "string",
+      enum: ["1.0.0", "1.1.0", "1.2.0", "1.3.0"],
+      description: "Version of the dfl-ux-paths schema this file conforms to. v1.1.0 adds optional navigation_path, prerequisites, test_metadata, and richer flow step objects. v1.2.0 adds optional screen.source_ref (screen\u2192repo file link) and screen.screenshots[] (per platform\xD7orientation), and documents `route` as the canonical shared route nomenclature for 1:1 cross-app mapping. v1.3.0 adds optional spec-first authoring fields: top-level `source` (build|spec) and `phases[]`, plus optional `phase`/`description` on screens and flows."
+    },
+    app_id: {
+      type: "string",
+      minLength: 1,
+      description: "Stable identifier for the app (e.g. 'dfl-learn-mobile')."
+    },
+    app_version: {
+      type: "string",
+      pattern: "^\\d{4}-\\d{2}-\\d{2}-[0-9a-f]{4,40}$",
+      description: 'App build identifier in the form YYYY-MM-DD-<git-sha-short>. A file authored before any build exists uses the zero-sha form `YYYY-MM-DD-0000000` that `dfl-ux-paths init` already emits, and should also set `source: "spec"`.'
+    },
+    source: {
+      type: "string",
+      enum: ["build", "spec"],
+      description: "v1.3 \u2014 provenance of this file. 'build' (the assumed default when omitted) means it was derived from a shipped build, so `route` values are real and source_ref/screenshots are meaningful. 'spec' means it was authored from a requirement document before the code exists: routes are PROPOSED nomenclature, app_version carries a zero-sha, and the absence of source_ref/screenshots/test_metadata.base_url is expected rather than a gap. Optional, additive."
+    },
+    phases: {
+      type: "array",
+      items: { $ref: "#/$defs/phase" },
+      description: "v1.3 \u2014 the app's delivery-phase vocabulary, declared once and referenced by `screen.phase` / `flow.phase`. Phase ids are free-form on purpose (every product names its phases differently). Mark a phase `optional: true` when the requirement explicitly parks it outside committed scope. Optional, additive."
+    },
+    generated_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO-8601 timestamp when this snapshot was generated."
+    },
+    tech_stack: {
+      type: "array",
+      items: { type: "string" },
+      description: "List of tech-stack tags (e.g. 'react-native', 'expo', 'powersync')."
+    },
+    test_metadata: {
+      $ref: "#/$defs/testMetadata",
+      description: "v1.1 \u2014 app-level metadata used by e2e-user-persona / Playwright skills to bootstrap a session (auth strategy, default viewport, base URL)."
+    },
+    screens: {
+      type: "array",
+      items: { $ref: "#/$defs/screen" }
+    },
+    flows: {
+      type: "array",
+      items: { $ref: "#/$defs/flow" }
+    },
+    dead_code: {
+      type: "array",
+      items: { $ref: "#/$defs/deadCodeEntry" }
+    }
+  },
+  $defs: {
+    phase: {
+      type: "object",
+      required: ["id"],
+      additionalProperties: false,
+      description: "v1.3 \u2014 one entry in the app's delivery-phase vocabulary.",
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Stable phase id referenced by `screen.phase` / `flow.phase` (e.g. 'alpha', 'beta', 'mvp', 'optional')."
+        },
+        label: {
+          type: "string",
+          description: "Human-readable phase name."
+        },
+        description: {
+          type: "string",
+          description: "What this phase covers \u2014 ideally quoting the source requirement rather than paraphrasing it."
+        },
+        optional: {
+          type: "boolean",
+          description: "True when the requirement explicitly parks this phase outside committed scope (e.g. 'eventual landing, not in MVP'). Viewers and generated Mermaid MUST render it as visually distinct from in-scope work, so a reader never mistakes parked work for a commitment."
+        }
+      }
+    },
+    screen: {
+      type: "object",
+      required: ["id", "name"],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Stable screen identifier (snake_case recommended). REQUIRED. This is the STICKY 1:1 JOIN KEY across apps: cross-app comparators (web \u2194 mobile, old build \u2194 new build) pair screens by shared `id`. Treat it as a contract \u2014 keep ids stable across versions and identical across apps you intend to map 1:1, or diffs/parity comparisons break."
+        },
+        name: {
+          type: "string",
+          minLength: 1,
+          description: "Human-readable screen name."
+        },
+        route: {
+          type: "string",
+          description: "v1.2 \u2014 canonical SHARED route nomenclature for 1:1 cross-app mapping (e.g. 'studio/project/:id/editor'). Lets two apps (web \u2194 mobile) map by the same route name even when their real URLs/deep-links differ. Also doubles as the screen's route/path/deep-link when the app uses a single URL scheme. Use ':param' for dynamic segments. Optional, additive."
+        },
+        description: {
+          type: "string",
+          description: "v1.3 \u2014 free-form prose describing this screen. For a spec-first file the description IS the requirement, so keep it faithful to the source document. Optional, additive."
+        },
+        phase: {
+          type: "string",
+          minLength: 1,
+          description: "v1.3 \u2014 id of the phase (from top-level `phases[]`) this screen belongs to. Optional, additive."
+        },
+        source_ref: {
+          $ref: "#/$defs/sourceRef",
+          description: "v1.2 \u2014 link from this screen to the repo file(s) that render it (route/page/modal component). Figma-Code-Connect style. Optional, additive \u2014 populated by the route\u2192file resolver (bin/resolve-routes.mjs) or by hand."
+        },
+        screenshots: {
+          type: "array",
+          items: { $ref: "#/$defs/screenshot" },
+          description: "v1.2 \u2014 rendered screenshots of this screen, one entry per platform\xD7orientation(\xD7viewport). URLs are committed (e.g. S3 via supabase-upload) so humans AND agents view the same image for vision-first comparison. Optional, additive."
+        },
+        components: {
+          type: "array",
+          items: { type: "string" },
+          description: "Component identifiers rendered on this screen."
+        },
+        api_calls: {
+          type: "array",
+          items: { type: "string" },
+          description: "API endpoints or RPC calls invoked from this screen."
+        },
+        actions: {
+          type: "array",
+          items: { $ref: "#/$defs/action" }
+        },
+        navigation_path: {
+          type: "array",
+          items: { $ref: "#/$defs/navigationStep" },
+          description: "v1.1 \u2014 ordered list of UI actions to navigate TO this screen from the app entrypoint. Used by e2e-user-persona to auto-generate persona scripts instead of LLM-driven discovery. When multiple navigationStep entries are present, the runner tries them in order and the first matching selector wins (useful for resilience across renames)."
+        },
+        prerequisites: {
+          $ref: "#/$defs/prerequisites",
+          description: "v1.1 \u2014 preconditions that must hold for this screen to be reachable / functional."
+        }
+      }
+    },
+    sourceRef: {
+      type: "object",
+      required: ["component_file"],
+      additionalProperties: false,
+      description: "v1.2 \u2014 points a screen at the repo file(s) that render it.",
+      properties: {
+        component_file: {
+          type: "string",
+          minLength: 1,
+          description: "Repo-relative path to the route/page/modal component that renders this screen (e.g. 'app/studio/[id]/editor.tsx' for Expo Router, 'app/studio/[id]/editor/page.tsx' for Next app-router). This is what the route\u2192file resolver emits."
+        },
+        file_path_chain: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "Optional \u2014 ordered repo-relative paths from the app entry (e.g. 'App.tsx' / 'app/_layout.tsx') down to the component, giving the 'tree' from app root to this screen's renderer."
+        }
+      }
+    },
+    screenshot: {
+      type: "object",
+      required: ["platform", "orientation", "url"],
+      additionalProperties: false,
+      description: "v1.2 \u2014 one rendered screenshot of a screen, keyed by platform\xD7orientation(\xD7viewport).",
+      properties: {
+        platform: {
+          type: "string",
+          enum: ["web", "mobile"],
+          description: "Rendering platform the screenshot was captured on."
+        },
+        orientation: {
+          type: "string",
+          enum: ["portrait", "landscape"],
+          description: "Device/viewport orientation."
+        },
+        viewport: {
+          type: "string",
+          description: "Optional viewport dimensions string, e.g. '375x812' or '1440x900'."
+        },
+        url: {
+          type: "string",
+          format: "uri",
+          description: "Public URL of the committed screenshot (e.g. S3 via supabase-upload)."
+        },
+        captured_at: {
+          type: "string",
+          format: "date-time",
+          description: "Optional ISO-8601 timestamp when the screenshot was captured."
+        }
+      }
+    },
+    action: {
+      type: "object",
+      required: ["id", "label"],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1
+        },
+        label: {
+          type: "string",
+          minLength: 1
+        },
+        next_screen: {
+          type: "string",
+          description: "Screen id the user lands on after this action."
+        },
+        side_effect: {
+          type: "string",
+          description: "Free-form description of side effect (mutation, analytics, etc.)."
+        }
+      }
+    },
+    flow: {
+      type: "object",
+      required: ["name", "start", "steps"],
+      additionalProperties: false,
+      properties: {
+        name: {
+          type: "string",
+          minLength: 1
+        },
+        description: {
+          type: "string",
+          description: "v1.3 \u2014 free-form prose describing what this flow accomplishes and why it matters. Optional, additive."
+        },
+        phase: {
+          type: "string",
+          minLength: 1,
+          description: "v1.3 \u2014 id of the phase (from top-level `phases[]`) this flow belongs to. Optional, additive."
+        },
+        start: {
+          type: "string",
+          minLength: 1,
+          description: "Screen id where the flow starts."
+        },
+        steps: {
+          type: "array",
+          items: {
+            oneOf: [
+              {
+                type: "string",
+                description: "v1.0 \u2014 screen id traversed in this flow."
+              },
+              {
+                $ref: "#/$defs/flowStepObject"
+              }
+            ]
+          },
+          description: "Ordered list of flow steps. v1.0 accepts plain screen ids (strings); v1.1 additionally accepts step objects with action/selector/target_screen for executable scripts. Mixed arrays are allowed during migration."
+        },
+        actions: {
+          type: "array",
+          items: { type: "string" },
+          description: "Ordered list of action ids exercised during this flow."
+        },
+        tested_by: {
+          type: "array",
+          items: { type: "string" },
+          description: "References to tests (file paths, test names) that cover this flow."
+        }
+      }
+    },
+    flowStepObject: {
+      type: "object",
+      required: ["screen"],
+      additionalProperties: false,
+      properties: {
+        screen: {
+          type: "string",
+          minLength: 1,
+          description: "Screen id where this step is executed."
+        },
+        action: {
+          type: "string",
+          description: "Action verb (tap, type, scroll, swipe, navigate, wait, assert, etc.)."
+        },
+        selector: {
+          type: "string",
+          description: "Playwright-compatible selector (e.g. 'text=Next', 'role=button[name=Save]', 'css=[data-testid=foo]')."
+        },
+        value: {
+          type: "string",
+          description: "Optional value to type / select / assert."
+        },
+        target_screen: {
+          type: "string",
+          description: "Screen id the user lands on after this step."
+        },
+        wait_for_target: {
+          type: "string",
+          description: "Selector / condition to wait for to confirm the target screen rendered."
+        },
+        note: {
+          type: "string",
+          description: "Free-form annotation for humans / debugging."
+        }
+      }
+    },
+    navigationStep: {
+      type: "object",
+      required: ["selector", "action"],
+      additionalProperties: false,
+      properties: {
+        selector: {
+          type: "string",
+          minLength: 1,
+          description: "Playwright-compatible selector (e.g. 'text=Studio', 'role=tab[name=Studio]', 'css=[data-testid=studio-tab]')."
+        },
+        action: {
+          type: "string",
+          enum: ["tap", "click", "type", "scroll", "swipe", "navigate", "wait", "assert"],
+          description: "Interaction primitive to execute."
+        },
+        value: {
+          type: "string",
+          description: "Optional value for type/select/assert."
+        },
+        wait_for: {
+          type: "string",
+          description: "Selector / condition to wait for after performing the action to confirm success."
+        },
+        note: {
+          type: "string",
+          description: "Free-form annotation."
+        }
+      }
+    },
+    prerequisites: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        auth_required: {
+          type: "boolean",
+          description: "True if a logged-in user session is required to reach this screen."
+        },
+        auth_role: {
+          type: "string",
+          description: "Optional \u2014 specific role required (e.g. 'admin', 'instructor'). Omit for any authenticated user."
+        },
+        data_required: {
+          type: "array",
+          items: { type: "string" },
+          description: "Free-form descriptions of DB/state preconditions (e.g. 'lesson_studio.projects has >= 0 rows')."
+        },
+        preconditions_in_app: {
+          type: "array",
+          items: { type: "string" },
+          description: "Free-form descriptions of in-app preconditions (feature flag enabled, onboarding complete, etc.)."
+        },
+        feature_flags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Feature flag identifiers that must be enabled."
+        }
+      }
+    },
+    testMetadata: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        auth_strategy: {
+          type: "string",
+          description: "Brief description of how to authenticate (e.g. 'supabase-anon + CLAUDE_SMOKE creds', 'magic-link', 'oauth google')."
+        },
+        default_viewport: {
+          type: "string",
+          enum: ["mobile", "tablet", "desktop", "responsive"],
+          description: "Hint for test runners \u2014 preferred viewport for this app."
+        },
+        base_url: {
+          type: "string",
+          format: "uri",
+          description: "Production / smoke-target base URL (e.g. 'https://mobile.devfellowship.com/')."
+        },
+        test_user_secret_path: {
+          type: "string",
+          description: "Infisical path to credentials suitable for smoke tests (e.g. '/shared/CLAUDE_SMOKE_USERNAME')."
+        },
+        notes: {
+          type: "string",
+          description: "Free-form notes for test authors / persona-script generators."
+        }
+      }
+    },
+    deadCodeEntry: {
+      type: "object",
+      required: ["component", "reason"],
+      additionalProperties: false,
+      properties: {
+        component: {
+          type: "string",
+          minLength: 1
+        },
+        reason: {
+          type: "string",
+          minLength: 1
+        }
+      }
+    }
+  }
+};
+
 // src/cli/ux-paths/lib/load-schema.ts
-var SCHEMA_URL = "https://raw.githubusercontent.com/devfellowship/dfl-ux-paths/main/schema/v1.json";
-var cached = null;
 async function loadSchemaV1() {
-  if (cached) return cached;
-  let res;
-  try {
-    res = await fetch(SCHEMA_URL);
-  } catch (err) {
-    throw new Error(
-      `Unable to fetch the UX Paths schema from ${SCHEMA_URL}: ${err.message}`
-    );
-  }
-  if (!res.ok) {
-    throw new Error(
-      `Unable to fetch the UX Paths schema from ${SCHEMA_URL}: HTTP ${res.status} ${res.statusText}`
-    );
-  }
-  cached = await res.json();
-  return cached;
+  return v1_schema_default;
 }
 
 // src/cli/ux-paths/commands/validate.ts

package/dist/testing.cjs

@@ -0,0 +1,171 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var testing_exports = {};
+__export(testing_exports, {
+  IAM_MEMBER_MIN_LEVEL: () => IAM_MEMBER_MIN_LEVEL,
+  VacuousVerificationError: () => VacuousVerificationError,
+  assertNotVacuouslyEmpty: () => assertNotVacuouslyEmpty,
+  classifyEmptiness: () => classifyEmptiness,
+  iamMemberProbe: () => iamMemberProbe
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/testing/emptiness.ts
+function classifyEmptiness(input) {
+  const { rowCount, deniedSignalPresent, viewerIsAuthorized } = input;
+  if (rowCount > 0) {
+    return {
+      verdict: "populated",
+      reason: `Surface rendered ${rowCount} row(s); the result is non-empty, so there is no emptiness to disambiguate.`
+    };
+  }
+  if (deniedSignalPresent) {
+    return {
+      verdict: "denied",
+      reason: "Surface rendered 0 rows AND an explicit permission-denied signal. The app failed loud, so the emptiness is attributable to a stated authorization failure rather than to a silent RLS filter \u2014 an assertion on this state is meaningful."
+    };
+  }
+  if (viewerIsAuthorized === true) {
+    return {
+      verdict: "genuinely-empty",
+      reason: "Surface rendered 0 rows with no permission-denied signal, and an independent authorization probe confirmed the viewer COULD have seen rows. The emptiness therefore reflects the data, not the viewer's access."
+    };
+  }
+  const authClause = viewerIsAuthorized === false ? "an independent probe reported the viewer is NOT authorized" : "the viewer's authorization could not be confirmed (unknown)";
+  return {
+    verdict: "vacuous",
+    reason: `Surface rendered 0 rows, the page rendered NO permission-denied signal, and ${authClause}. Supabase RLS hides unauthorized rows as HTTP 200 with an empty body, which is byte-identical to a genuinely empty result \u2014 so this emptiness is indistinguishable from lack of access and the check proves nothing. Fix by supplying an independent authorization signal (e.g. \`iamMemberProbe\`), by using an identity that can see rows, or by making the surface render an explicit permission-denied state.`
+  };
+}
+
+// src/testing/assert-not-vacuously-empty.ts
+var VacuousVerificationError = class extends Error {
+  constructor(details) {
+    super(
+      [
+        `Vacuous verification on "${details.surface}": this check proves nothing.`,
+        "",
+        `  \u2022 the surface returned ${details.rowCount} rows (nothing to assert against)`,
+        "  \u2022 the page rendered NO permission-denied signal, so the app did not fail loud",
+        details.viewerIsAuthorized === false ? "  \u2022 the viewer is known NOT to be authorized" : "  \u2022 the viewer's authorization could NOT be confirmed",
+        "",
+        details.reason
+      ].join("\n")
+    );
+    this.verdict = "vacuous";
+    this.name = "VacuousVerificationError";
+    this.surface = details.surface;
+    this.rowCount = details.rowCount;
+    this.deniedSignalPresent = details.deniedSignalPresent;
+    this.viewerIsAuthorized = details.viewerIsAuthorized;
+    this.reason = details.reason;
+  }
+};
+async function resolveAuthorization(input) {
+  if (input === void 0) return "unknown";
+  if (typeof input !== "function") return input;
+  try {
+    const result = await input();
+    return result === true || result === false ? result : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function resolveRowCount(page, opts) {
+  if (opts.countText) {
+    const text = await page.locator(opts.countTextSelector ?? "body").innerText();
+    for (const rawLine of text.split("\n")) {
+      const match = opts.countText.exec(rawLine.trim());
+      if (match) {
+        const parsed = Number(match[1]);
+        if (Number.isFinite(parsed)) return parsed;
+      }
+    }
+    if (!opts.rowSelector) {
+      throw new Error(
+        `assertNotVacuouslyEmpty: countText ${String(opts.countText)} matched no line of "${opts.countTextSelector ?? "body"}". The row count is unreadable, so no verdict is possible \u2014 fix the pattern or pass rowSelector.`
+      );
+    }
+  }
+  if (opts.rowSelector) return page.locator(opts.rowSelector).count();
+  throw new Error(
+    "assertNotVacuouslyEmpty: pass countText and/or rowSelector \u2014 without one there is no row count to classify."
+  );
+}
+async function assertNotVacuouslyEmpty(page, opts = {}) {
+  const surface = opts.surface ?? "unnamed surface";
+  const rowCount = await resolveRowCount(page, opts);
+  const deniedSignalPresent = opts.deniedSelector ? await page.locator(opts.deniedSelector).count() > 0 : false;
+  const viewerIsAuthorized = await resolveAuthorization(opts.viewerIsAuthorized);
+  const { verdict, reason } = classifyEmptiness({
+    rowCount,
+    deniedSignalPresent,
+    viewerIsAuthorized
+  });
+  if (verdict === "vacuous") {
+    throw new VacuousVerificationError({
+      surface,
+      rowCount,
+      deniedSignalPresent,
+      viewerIsAuthorized,
+      reason
+    });
+  }
+  return verdict;
+}
+
+// src/testing/iam-member-probe.ts
+var IAM_MEMBER_MIN_LEVEL = 50;
+function readLevel(row) {
+  if (typeof row !== "object" || row === null) return null;
+  const level = row.level;
+  if (typeof level === "number" && Number.isFinite(level)) return level;
+  if (typeof level === "string" && level.trim() !== "") {
+    const parsed = Number(level);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+async function iamMemberProbe(supabaseClient, opts = {}) {
+  const minLevel = opts.minLevel ?? IAM_MEMBER_MIN_LEVEL;
+  const rpcName = opts.rpcName ?? "get_my_iam_role";
+  let data;
+  let error;
+  try {
+    ({ data, error } = await supabaseClient.rpc(rpcName));
+  } catch {
+    return "unknown";
+  }
+  if (error) return "unknown";
+  const rows = Array.isArray(data) ? data : data == null ? [] : [data];
+  if (rows.length === 0) return "unknown";
+  const levels = rows.map(readLevel).filter((l) => l !== null);
+  if (levels.length === 0) return "unknown";
+  return levels.some((level) => level >= minLevel);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IAM_MEMBER_MIN_LEVEL,
+  VacuousVerificationError,
+  assertNotVacuouslyEmpty,
+  classifyEmptiness,
+  iamMemberProbe
+});

package/dist/testing.d.cts

@@ -0,0 +1,210 @@
+/**
+ * Layer 1 — the pure decision. No I/O, no Playwright, no Supabase.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Agents verify UI through Playwright using a shared smoke identity that has
+ * IAM global level 0. Supabase RLS on `iam.is_member()`-gated tables returns
+ * ZERO ROWS WITH HTTP 200 — not 403. So the page renders "no results" and an
+ * assertion like `expect(rows).toHaveCount(0)` or "the page loaded without an
+ * error" passes VACUOUSLY: satisfied by absence of permission rather than by
+ * the state under test.
+ *
+ * Measured 2026-08-07: spec-builder `/history` showed "0 registros" to the
+ * smoke account while `work.ai_spec_inputs` held 17 rows. Every assertion on
+ * that page was green.
+ *
+ * THE HONEST PART
+ * ---------------
+ * PostgREST cannot tell "RLS hid it" from "genuinely empty" — both are
+ * `200 []`. There is no detector that can recover the difference from the
+ * response alone, and this module does not pretend otherwise. What it does
+ * instead is NAME the ambiguity and refuse to let a test claim a green it did
+ * not earn: an empty surface only proves something when we have an
+ * INDEPENDENT signal that the viewer was authorized to see rows (or that the
+ * app told us, loudly, that it was not).
+ */
+/**
+ * The four states an empty-looking surface can actually be in.
+ *
+ * - `populated`       — rows are present. Nothing ambiguous.
+ * - `denied`          — empty, and the app rendered a permission-denied
+ *                       signal. The app failed LOUD; that is correct
+ *                       behaviour, and asserting emptiness here is meaningful.
+ * - `genuinely-empty` — empty, no denied signal, and we independently know the
+ *                       viewer WAS authorized. Safe: the emptiness is real.
+ * - `vacuous`         — empty, no denied signal, and the viewer's
+ *                       authorization is `false` or could not be confirmed.
+ *                       The check proves nothing. This is the failure.
+ */
+type EmptinessVerdict = "populated" | "denied" | "genuinely-empty" | "vacuous";
+interface ClassifyEmptinessInput {
+    /** How many rows/items the surface actually rendered. */
+    rowCount: number;
+    /**
+     * Did the page render an explicit permission-denied affordance (banner,
+     * `data-testid="access-denied"`, 403 state)? An app that fails loud is
+     * verifiable; an app that renders a silent empty list is not.
+     */
+    deniedSignalPresent: boolean;
+    /**
+     * INDEPENDENT authorization signal — must NOT be derived from the same
+     * response whose emptiness is in question, or the reasoning is circular.
+     * `'unknown'` is the correct value when no independent probe ran; it is
+     * deliberately treated exactly as harshly as `false`.
+     */
+    viewerIsAuthorized: boolean | "unknown";
+}
+interface EmptinessClassification {
+    verdict: EmptinessVerdict;
+    /** Human-readable justification, safe to embed in a failure message. */
+    reason: string;
+}
+/**
+ * Classify what an (apparently) empty surface actually proves.
+ *
+ * Pure function: same input, same verdict, no clock, no network. Every I/O
+ * concern lives in Layer 2 (`assertNotVacuouslyEmpty`).
+ */
+declare function classifyEmptiness(input: ClassifyEmptinessInput): EmptinessClassification;
+
+/**
+ * Structural (duck-typed) subset of the Playwright surface this entry needs.
+ *
+ * WHY NOT `import type { Page } from "@playwright/test"`
+ * -----------------------------------------------------
+ * `@devfellowship/components` is a runtime dependency of every DFL app.
+ * Adding Playwright — even as a type-only import — would put a ~100MB test
+ * runner into the dependency graph of production bundles and would make this
+ * entry impossible to unit-test without a browser. So we declare the three
+ * methods we actually call and nothing else.
+ *
+ * A real Playwright `Page` / `Locator` satisfies these interfaces
+ * structurally: no adapter, no cast, no `@playwright/test` in package.json.
+ * A plain object literal satisfies them too, which is how the tests work.
+ */
+/** The slice of a Playwright `Locator` used here. */
+interface LocatorLike {
+    /** Number of DOM elements the selector currently resolves to. */
+    count(): Promise<number>;
+    /** Rendered (visible) text of the resolved element. */
+    innerText(): Promise<string>;
+}
+/** The slice of a Playwright `Page` used here. */
+interface PageLike {
+    locator(selector: string): LocatorLike;
+}
+/**
+ * Minimal shape of a `supabase-js` client — only `.rpc()`, only the fields
+ * `iamMemberProbe` reads. Keeps `@supabase/supabase-js` out of this entry's
+ * imports entirely (it is an OPTIONAL peer dependency of the package).
+ */
+interface SupabaseRpcClientLike {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+
+/**
+ * Thrown when a surface's emptiness is indistinguishable from lack of access.
+ *
+ * This is NOT "the page is broken" — it is "this check cannot tell you whether
+ * the page is broken", which is the more dangerous state, because the default
+ * assertion would have passed.
+ */
+declare class VacuousVerificationError extends Error {
+    readonly verdict: EmptinessVerdict;
+    readonly surface: string;
+    readonly rowCount: number;
+    readonly deniedSignalPresent: boolean;
+    readonly viewerIsAuthorized: boolean | "unknown";
+    readonly reason: string;
+    constructor(details: {
+        surface: string;
+        rowCount: number;
+        deniedSignalPresent: boolean;
+        viewerIsAuthorized: boolean | "unknown";
+        reason: string;
+    });
+}
+interface AssertNotVacuouslyEmptyOptions {
+    /**
+     * Regex matched against the surface's rendered text, LINE BY LINE (each line
+     * trimmed), so anchored patterns work — e.g. `/^(\d+) registros?$/`.
+     * Capture group 1 must be the count.
+     */
+    countText?: RegExp;
+    /** CSS/testid selector whose element holds the count text. Default `body`. */
+    countTextSelector?: string;
+    /** Alternative to `countText`: count the elements matching this selector. */
+    rowSelector?: string;
+    /**
+     * Selector for the element/testid the app renders on permission denial.
+     * If the app has no such affordance, omit it — but then a denied surface is
+     * unverifiable by construction, which is exactly what `vacuous` reports.
+     */
+    deniedSelector?: string;
+    /**
+     * INDEPENDENT authorization signal. A thunk (e.g. `() => iamMemberProbe(sb)`)
+     * is awaited; if it throws, the result is `'unknown'`.
+     * Omitted defaults to `'unknown'` — treated as harshly as `false`.
+     */
+    viewerIsAuthorized?: boolean | "unknown" | (() => Promise<boolean | "unknown">);
+    /** Label used in the failure message. Default `unnamed surface`. */
+    surface?: string;
+}
+/**
+ * Layer 2 — the e2e adapter. Reads the three facts off a Playwright-ish page,
+ * hands them to the pure {@link classifyEmptiness}, and refuses to return a
+ * green it cannot justify.
+ *
+ * Returns the {@link EmptinessVerdict} for `populated`, `denied` and
+ * `genuinely-empty`. Throws {@link VacuousVerificationError} for `vacuous`.
+ *
+ * @example
+ * // Fails today against the level-0 smoke identity — by design.
+ * await assertNotVacuouslyEmpty(page, {
+ *   surface: "spec-builder /history",
+ *   countText: /^(\d+) registros?$/,
+ *   deniedSelector: '[data-testid="access-denied"]',
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function assertNotVacuouslyEmpty(page: PageLike, opts?: AssertNotVacuouslyEmptyOptions): Promise<EmptinessVerdict>;
+
+/**
+ * Default IAM level that counts as "member enough to see gated rows".
+ * Mirrors the threshold `iam.is_member()` enforces server-side.
+ */
+declare const IAM_MEMBER_MIN_LEVEL = 50;
+/**
+ * Independent authorization probe: ask the database who the caller is,
+ * instead of inferring it from the very response whose emptiness is in doubt.
+ *
+ * Calls the existing `get_my_iam_role()` RPC (already granted to
+ * `authenticated`; returns rows of `{ role_id, level }`) and resolves whether
+ * any granted role clears `minLevel` (default {@link IAM_MEMBER_MIN_LEVEL}).
+ *
+ * FAILS TO `'unknown'`, NEVER TO `true`. An RPC error, a null payload, a
+ * non-array payload, or rows carrying no readable `level` all mean "we did not
+ * learn anything" — and `'unknown'` is treated by `classifyEmptiness` exactly
+ * as harshly as `false`. A probe that guessed optimistically would reintroduce
+ * the very false-green this module exists to prevent.
+ *
+ * Note that an empty row set is `'unknown'` rather than `false`: a level-0
+ * identity may legitimately produce zero rows, but so does a broken grant, and
+ * the two are not distinguishable from here. Both block a green.
+ *
+ * @example
+ * await assertNotVacuouslyEmpty(page, {
+ *   countText: /^(\d+) registros?$/,
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function iamMemberProbe(supabaseClient: SupabaseRpcClientLike, opts?: {
+    minLevel?: number;
+    rpcName?: string;
+}): Promise<boolean | "unknown">;
+
+export { type AssertNotVacuouslyEmptyOptions, type ClassifyEmptinessInput, type EmptinessClassification, type EmptinessVerdict, IAM_MEMBER_MIN_LEVEL, type LocatorLike, type PageLike, type SupabaseRpcClientLike, VacuousVerificationError, assertNotVacuouslyEmpty, classifyEmptiness, iamMemberProbe };

package/dist/testing.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Layer 1 — the pure decision. No I/O, no Playwright, no Supabase.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Agents verify UI through Playwright using a shared smoke identity that has
+ * IAM global level 0. Supabase RLS on `iam.is_member()`-gated tables returns
+ * ZERO ROWS WITH HTTP 200 — not 403. So the page renders "no results" and an
+ * assertion like `expect(rows).toHaveCount(0)` or "the page loaded without an
+ * error" passes VACUOUSLY: satisfied by absence of permission rather than by
+ * the state under test.
+ *
+ * Measured 2026-08-07: spec-builder `/history` showed "0 registros" to the
+ * smoke account while `work.ai_spec_inputs` held 17 rows. Every assertion on
+ * that page was green.
+ *
+ * THE HONEST PART
+ * ---------------
+ * PostgREST cannot tell "RLS hid it" from "genuinely empty" — both are
+ * `200 []`. There is no detector that can recover the difference from the
+ * response alone, and this module does not pretend otherwise. What it does
+ * instead is NAME the ambiguity and refuse to let a test claim a green it did
+ * not earn: an empty surface only proves something when we have an
+ * INDEPENDENT signal that the viewer was authorized to see rows (or that the
+ * app told us, loudly, that it was not).
+ */
+/**
+ * The four states an empty-looking surface can actually be in.
+ *
+ * - `populated`       — rows are present. Nothing ambiguous.
+ * - `denied`          — empty, and the app rendered a permission-denied
+ *                       signal. The app failed LOUD; that is correct
+ *                       behaviour, and asserting emptiness here is meaningful.
+ * - `genuinely-empty` — empty, no denied signal, and we independently know the
+ *                       viewer WAS authorized. Safe: the emptiness is real.
+ * - `vacuous`         — empty, no denied signal, and the viewer's
+ *                       authorization is `false` or could not be confirmed.
+ *                       The check proves nothing. This is the failure.
+ */
+type EmptinessVerdict = "populated" | "denied" | "genuinely-empty" | "vacuous";
+interface ClassifyEmptinessInput {
+    /** How many rows/items the surface actually rendered. */
+    rowCount: number;
+    /**
+     * Did the page render an explicit permission-denied affordance (banner,
+     * `data-testid="access-denied"`, 403 state)? An app that fails loud is
+     * verifiable; an app that renders a silent empty list is not.
+     */
+    deniedSignalPresent: boolean;
+    /**
+     * INDEPENDENT authorization signal — must NOT be derived from the same
+     * response whose emptiness is in question, or the reasoning is circular.
+     * `'unknown'` is the correct value when no independent probe ran; it is
+     * deliberately treated exactly as harshly as `false`.
+     */
+    viewerIsAuthorized: boolean | "unknown";
+}
+interface EmptinessClassification {
+    verdict: EmptinessVerdict;
+    /** Human-readable justification, safe to embed in a failure message. */
+    reason: string;
+}
+/**
+ * Classify what an (apparently) empty surface actually proves.
+ *
+ * Pure function: same input, same verdict, no clock, no network. Every I/O
+ * concern lives in Layer 2 (`assertNotVacuouslyEmpty`).
+ */
+declare function classifyEmptiness(input: ClassifyEmptinessInput): EmptinessClassification;
+
+/**
+ * Structural (duck-typed) subset of the Playwright surface this entry needs.
+ *
+ * WHY NOT `import type { Page } from "@playwright/test"`
+ * -----------------------------------------------------
+ * `@devfellowship/components` is a runtime dependency of every DFL app.
+ * Adding Playwright — even as a type-only import — would put a ~100MB test
+ * runner into the dependency graph of production bundles and would make this
+ * entry impossible to unit-test without a browser. So we declare the three
+ * methods we actually call and nothing else.
+ *
+ * A real Playwright `Page` / `Locator` satisfies these interfaces
+ * structurally: no adapter, no cast, no `@playwright/test` in package.json.
+ * A plain object literal satisfies them too, which is how the tests work.
+ */
+/** The slice of a Playwright `Locator` used here. */
+interface LocatorLike {
+    /** Number of DOM elements the selector currently resolves to. */
+    count(): Promise<number>;
+    /** Rendered (visible) text of the resolved element. */
+    innerText(): Promise<string>;
+}
+/** The slice of a Playwright `Page` used here. */
+interface PageLike {
+    locator(selector: string): LocatorLike;
+}
+/**
+ * Minimal shape of a `supabase-js` client — only `.rpc()`, only the fields
+ * `iamMemberProbe` reads. Keeps `@supabase/supabase-js` out of this entry's
+ * imports entirely (it is an OPTIONAL peer dependency of the package).
+ */
+interface SupabaseRpcClientLike {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+
+/**
+ * Thrown when a surface's emptiness is indistinguishable from lack of access.
+ *
+ * This is NOT "the page is broken" — it is "this check cannot tell you whether
+ * the page is broken", which is the more dangerous state, because the default
+ * assertion would have passed.
+ */
+declare class VacuousVerificationError extends Error {
+    readonly verdict: EmptinessVerdict;
+    readonly surface: string;
+    readonly rowCount: number;
+    readonly deniedSignalPresent: boolean;
+    readonly viewerIsAuthorized: boolean | "unknown";
+    readonly reason: string;
+    constructor(details: {
+        surface: string;
+        rowCount: number;
+        deniedSignalPresent: boolean;
+        viewerIsAuthorized: boolean | "unknown";
+        reason: string;
+    });
+}
+interface AssertNotVacuouslyEmptyOptions {
+    /**
+     * Regex matched against the surface's rendered text, LINE BY LINE (each line
+     * trimmed), so anchored patterns work — e.g. `/^(\d+) registros?$/`.
+     * Capture group 1 must be the count.
+     */
+    countText?: RegExp;
+    /** CSS/testid selector whose element holds the count text. Default `body`. */
+    countTextSelector?: string;
+    /** Alternative to `countText`: count the elements matching this selector. */
+    rowSelector?: string;
+    /**
+     * Selector for the element/testid the app renders on permission denial.
+     * If the app has no such affordance, omit it — but then a denied surface is
+     * unverifiable by construction, which is exactly what `vacuous` reports.
+     */
+    deniedSelector?: string;
+    /**
+     * INDEPENDENT authorization signal. A thunk (e.g. `() => iamMemberProbe(sb)`)
+     * is awaited; if it throws, the result is `'unknown'`.
+     * Omitted defaults to `'unknown'` — treated as harshly as `false`.
+     */
+    viewerIsAuthorized?: boolean | "unknown" | (() => Promise<boolean | "unknown">);
+    /** Label used in the failure message. Default `unnamed surface`. */
+    surface?: string;
+}
+/**
+ * Layer 2 — the e2e adapter. Reads the three facts off a Playwright-ish page,
+ * hands them to the pure {@link classifyEmptiness}, and refuses to return a
+ * green it cannot justify.
+ *
+ * Returns the {@link EmptinessVerdict} for `populated`, `denied` and
+ * `genuinely-empty`. Throws {@link VacuousVerificationError} for `vacuous`.
+ *
+ * @example
+ * // Fails today against the level-0 smoke identity — by design.
+ * await assertNotVacuouslyEmpty(page, {
+ *   surface: "spec-builder /history",
+ *   countText: /^(\d+) registros?$/,
+ *   deniedSelector: '[data-testid="access-denied"]',
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function assertNotVacuouslyEmpty(page: PageLike, opts?: AssertNotVacuouslyEmptyOptions): Promise<EmptinessVerdict>;
+
+/**
+ * Default IAM level that counts as "member enough to see gated rows".
+ * Mirrors the threshold `iam.is_member()` enforces server-side.
+ */
+declare const IAM_MEMBER_MIN_LEVEL = 50;
+/**
+ * Independent authorization probe: ask the database who the caller is,
+ * instead of inferring it from the very response whose emptiness is in doubt.
+ *
+ * Calls the existing `get_my_iam_role()` RPC (already granted to
+ * `authenticated`; returns rows of `{ role_id, level }`) and resolves whether
+ * any granted role clears `minLevel` (default {@link IAM_MEMBER_MIN_LEVEL}).
+ *
+ * FAILS TO `'unknown'`, NEVER TO `true`. An RPC error, a null payload, a
+ * non-array payload, or rows carrying no readable `level` all mean "we did not
+ * learn anything" — and `'unknown'` is treated by `classifyEmptiness` exactly
+ * as harshly as `false`. A probe that guessed optimistically would reintroduce
+ * the very false-green this module exists to prevent.
+ *
+ * Note that an empty row set is `'unknown'` rather than `false`: a level-0
+ * identity may legitimately produce zero rows, but so does a broken grant, and
+ * the two are not distinguishable from here. Both block a green.
+ *
+ * @example
+ * await assertNotVacuouslyEmpty(page, {
+ *   countText: /^(\d+) registros?$/,
+ *   viewerIsAuthorized: () => iamMemberProbe(supabase),
+ * });
+ */
+declare function iamMemberProbe(supabaseClient: SupabaseRpcClientLike, opts?: {
+    minLevel?: number;
+    rpcName?: string;
+}): Promise<boolean | "unknown">;
+
+export { type AssertNotVacuouslyEmptyOptions, type ClassifyEmptinessInput, type EmptinessClassification, type EmptinessVerdict, IAM_MEMBER_MIN_LEVEL, type LocatorLike, type PageLike, type SupabaseRpcClientLike, VacuousVerificationError, assertNotVacuouslyEmpty, classifyEmptiness, iamMemberProbe };

package/dist/testing.js

@@ -0,0 +1,140 @@
+// src/testing/emptiness.ts
+function classifyEmptiness(input) {
+  const { rowCount, deniedSignalPresent, viewerIsAuthorized } = input;
+  if (rowCount > 0) {
+    return {
+      verdict: "populated",
+      reason: `Surface rendered ${rowCount} row(s); the result is non-empty, so there is no emptiness to disambiguate.`
+    };
+  }
+  if (deniedSignalPresent) {
+    return {
+      verdict: "denied",
+      reason: "Surface rendered 0 rows AND an explicit permission-denied signal. The app failed loud, so the emptiness is attributable to a stated authorization failure rather than to a silent RLS filter \u2014 an assertion on this state is meaningful."
+    };
+  }
+  if (viewerIsAuthorized === true) {
+    return {
+      verdict: "genuinely-empty",
+      reason: "Surface rendered 0 rows with no permission-denied signal, and an independent authorization probe confirmed the viewer COULD have seen rows. The emptiness therefore reflects the data, not the viewer's access."
+    };
+  }
+  const authClause = viewerIsAuthorized === false ? "an independent probe reported the viewer is NOT authorized" : "the viewer's authorization could not be confirmed (unknown)";
+  return {
+    verdict: "vacuous",
+    reason: `Surface rendered 0 rows, the page rendered NO permission-denied signal, and ${authClause}. Supabase RLS hides unauthorized rows as HTTP 200 with an empty body, which is byte-identical to a genuinely empty result \u2014 so this emptiness is indistinguishable from lack of access and the check proves nothing. Fix by supplying an independent authorization signal (e.g. \`iamMemberProbe\`), by using an identity that can see rows, or by making the surface render an explicit permission-denied state.`
+  };
+}
+
+// src/testing/assert-not-vacuously-empty.ts
+var VacuousVerificationError = class extends Error {
+  constructor(details) {
+    super(
+      [
+        `Vacuous verification on "${details.surface}": this check proves nothing.`,
+        "",
+        `  \u2022 the surface returned ${details.rowCount} rows (nothing to assert against)`,
+        "  \u2022 the page rendered NO permission-denied signal, so the app did not fail loud",
+        details.viewerIsAuthorized === false ? "  \u2022 the viewer is known NOT to be authorized" : "  \u2022 the viewer's authorization could NOT be confirmed",
+        "",
+        details.reason
+      ].join("\n")
+    );
+    this.verdict = "vacuous";
+    this.name = "VacuousVerificationError";
+    this.surface = details.surface;
+    this.rowCount = details.rowCount;
+    this.deniedSignalPresent = details.deniedSignalPresent;
+    this.viewerIsAuthorized = details.viewerIsAuthorized;
+    this.reason = details.reason;
+  }
+};
+async function resolveAuthorization(input) {
+  if (input === void 0) return "unknown";
+  if (typeof input !== "function") return input;
+  try {
+    const result = await input();
+    return result === true || result === false ? result : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function resolveRowCount(page, opts) {
+  if (opts.countText) {
+    const text = await page.locator(opts.countTextSelector ?? "body").innerText();
+    for (const rawLine of text.split("\n")) {
+      const match = opts.countText.exec(rawLine.trim());
+      if (match) {
+        const parsed = Number(match[1]);
+        if (Number.isFinite(parsed)) return parsed;
+      }
+    }
+    if (!opts.rowSelector) {
+      throw new Error(
+        `assertNotVacuouslyEmpty: countText ${String(opts.countText)} matched no line of "${opts.countTextSelector ?? "body"}". The row count is unreadable, so no verdict is possible \u2014 fix the pattern or pass rowSelector.`
+      );
+    }
+  }
+  if (opts.rowSelector) return page.locator(opts.rowSelector).count();
+  throw new Error(
+    "assertNotVacuouslyEmpty: pass countText and/or rowSelector \u2014 without one there is no row count to classify."
+  );
+}
+async function assertNotVacuouslyEmpty(page, opts = {}) {
+  const surface = opts.surface ?? "unnamed surface";
+  const rowCount = await resolveRowCount(page, opts);
+  const deniedSignalPresent = opts.deniedSelector ? await page.locator(opts.deniedSelector).count() > 0 : false;
+  const viewerIsAuthorized = await resolveAuthorization(opts.viewerIsAuthorized);
+  const { verdict, reason } = classifyEmptiness({
+    rowCount,
+    deniedSignalPresent,
+    viewerIsAuthorized
+  });
+  if (verdict === "vacuous") {
+    throw new VacuousVerificationError({
+      surface,
+      rowCount,
+      deniedSignalPresent,
+      viewerIsAuthorized,
+      reason
+    });
+  }
+  return verdict;
+}
+
+// src/testing/iam-member-probe.ts
+var IAM_MEMBER_MIN_LEVEL = 50;
+function readLevel(row) {
+  if (typeof row !== "object" || row === null) return null;
+  const level = row.level;
+  if (typeof level === "number" && Number.isFinite(level)) return level;
+  if (typeof level === "string" && level.trim() !== "") {
+    const parsed = Number(level);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+async function iamMemberProbe(supabaseClient, opts = {}) {
+  const minLevel = opts.minLevel ?? IAM_MEMBER_MIN_LEVEL;
+  const rpcName = opts.rpcName ?? "get_my_iam_role";
+  let data;
+  let error;
+  try {
+    ({ data, error } = await supabaseClient.rpc(rpcName));
+  } catch {
+    return "unknown";
+  }
+  if (error) return "unknown";
+  const rows = Array.isArray(data) ? data : data == null ? [] : [data];
+  if (rows.length === 0) return "unknown";
+  const levels = rows.map(readLevel).filter((l) => l !== null);
+  if (levels.length === 0) return "unknown";
+  return levels.some((level) => level >= minLevel);
+}
+export {
+  IAM_MEMBER_MIN_LEVEL,
+  VacuousVerificationError,
+  assertNotVacuouslyEmpty,
+  classifyEmptiness,
+  iamMemberProbe
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devfellowship/components",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "DFL Design System — UI components, hooks, utils and providers",
   "type": "module",
   "sideEffects": [
@@ -27,6 +27,11 @@
       "import": "./dist/providers.js",
       "require": "./dist/providers.cjs"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    },
     "./styles": "./dist/styles/theme.css",
     "./shadcn": "./dist/styles/shadcn.css",
     "./tokens": "./dist/styles/tokens.css",
@@ -52,7 +57,8 @@
     "prepublishOnly": "npm run build",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "lint:no-docs": "node scripts/check-no-storybook-docs.mjs"
+    "lint:no-docs": "node scripts/check-no-storybook-docs.mjs",
+    "check:cli-offline": "node scripts/check-cli-bundle-offline.mjs"
   },
   "peerDependencies": {
     "@supabase/supabase-js": ">=2.0.0",