@usefidel/contracts 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @usefidel/contracts
+
+Shared contracts between Fidel surfaces. Currently the **run-error taxonomy** only:
+the set of typed error codes a validation run can fail with, their user-facing
+messages, whether each is retryable, and a helper for presenting a failed run.
+
+This package exists so that Fidel's web app, browser extension, GitHub Action and
+CI runner all describe the same failure with the same code and the same wording,
+rather than each keeping its own drifting copy.
+
+## Why it is public
+
+It is published publicly so build environments can install it without
+authenticating to a private registry. **Public availability is not a licence.**
+See below.
+
+It contains no proprietary logic — no matching, scoring, or diffing code. Error
+codes and their messages only.
+
+## Install
+
+```sh
+npm install @usefidel/contracts
+```
+
+## Use
+
+```js
+import { RUN_ERROR_CODES, resolveRunDisplay } from '@usefidel/contracts';
+// or
+import { resolveRunDisplay } from '@usefidel/contracts/run-errors';
+```
+
+Ships ESM with TypeScript declarations. No runtime dependencies.
+
+## Versioning
+
+Semver. The error-code set is additive within a major version: new codes may
+appear in a minor release, and existing codes are neither removed nor given new
+meanings without a major bump.
+
+## Licence
+
+**UNLICENSED — all rights reserved.** Being downloadable from npm does not grant
+permission to use, copy, modify, or redistribute this package. It is published for
+Fidel's own build and deployment pipelines. If you want to use it, ask first:
+support@usefidel.com
+
+## Contributing
+
+Not open to outside contributions. Issues and pull requests have nowhere to go —
+the source lives in a private repository.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaErrorToCode, resolveRunDisplay, } from './run-errors.js';
+export type { RunErrorCode, RunErrorMeta, ErrorMapping, RunDisplay, } from './run-errors.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+// @usefidel/contracts — the entire public surface.
+//
+// SCOPE IS DELIBERATELY NARROW (plan 046, decision D5). This package exists so
+// `usefidel/fidel-web` can render run errors without importing from the monorepo.
+// It carries CONTRACTS ONLY: shapes, codes, and the presentation helpers that
+// turn a code into user-facing copy.
+//
+// It must never carry:
+//   - matching-engine code of any kind
+//   - backend implementation (Supabase queries, edge-function logic, Lambda calls)
+//   - credentials, endpoints, or anything environment-specific
+//
+// The narrowness is the security property. This package is installable by a
+// contractor; everything in it is readable by one. Widening it widens that.
+//
+// Adding an export here is an architectural change, not a convenience — it needs
+// the same review as any cross-surface contract.
+export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaErrorToCode, resolveRunDisplay, } from './run-errors.js';

package/dist/run-errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * run-errors.ts — Canonical run error taxonomy.
+ *
+ * Single source of truth for all typed error codes, their human-readable
+ * messages, retryability, and display logic.
+ *
+ * VENDOR-SYNC: This file is vendored to:
+ *   - lambda/lib/run-errors.ts        (exact copy — Lambda is self-contained)
+ *   - github-action/src/run-errors.ts (exact copy — github-action can't import Supabase _shared)
+ *   - runner/src/run-errors.js        (intentional-diff: plain JS, no TypeScript)
+ *
+ * The webapp imports via `@fidel/shared/run-errors` alias → extension/src/lib/run-errors.ts.
+ * The extension copy is itself vendored from here (registered in vendor-sync.config.json).
+ *
+ * When editing this file, run `npx tsx scripts/check-vendor-sync.ts` and
+ * update all consumer copies.
+ */
+export declare const RUN_ERROR_CODES: readonly ["TARGET_AUTH_WALL", "TARGET_UNREACHABLE", "TARGET_TIMEOUT", "TARGET_CSP_BLOCKED", "FIGMA_ACCESS_DENIED", "FIGMA_TOKEN_EXPIRED", "FIGMA_NOT_FOUND", "FIGMA_RATE_LIMITED", "PIPELINE_TIMEOUT", "PIPELINE_ERROR", "ZERO_ELEMENTS_MATCHED", "PERSIST_FAILED", "SESSION_EXPIRED", "INVALID_REFERENCE_URL", "INVALID_TARGET_URL", "DESIGN_SYSTEM_NOT_AVAILABLE", "DESIGN_SYSTEM_CONTEXT_NOT_AVAILABLE", "DESIGN_SYSTEM_INCOMPATIBLE", "FLOW_STEP_FAILED", "UNKNOWN_ERROR"];
+export type RunErrorCode = (typeof RUN_ERROR_CODES)[number];
+export interface RunErrorMeta {
+    retryable: boolean;
+    /** Full sentence shown in error banners / report pages. No HTTP jargon. */
+    userMessage: string;
+    /** Short label (2–4 words) for badges or compact lists. */
+    shortLabel: string;
+}
+export declare const ERROR_CODE_META: Record<RunErrorCode, RunErrorMeta>;
+export interface ErrorMapping {
+    code: RunErrorCode;
+    message: string;
+    retryable: boolean;
+}
+/**
+ * Map a raw Snapshot Lambda error string to a typed RunErrorCode.
+ *
+ * Input format from Snapshot Lambda: "SNAPSHOT_ERROR:<status>:<detail>"
+ * where detail contains Chromium net::ERR_* codes.
+ */
+export declare function mapSnapshotErrorToCode(rawError: string | undefined): ErrorMapping;
+/**
+ * Map a raw Figma fetch error string to a typed RunErrorCode.
+ */
+export declare function mapFigmaErrorToCode(rawError: string): ErrorMapping;
+export interface RunDisplay {
+    title: string;
+    description: string;
+    retryable: boolean;
+    action?: 'reconnect_figma' | 'upgrade' | 'check_url' | 'reconnect_environment';
+}
+/**
+ * Derive a user-facing display object from a validation_runs row.
+ * Used by webapp, GitHub Action comment formatter, and the runner.
+ */
+export declare function resolveRunDisplay(run: {
+    status: string;
+    error_code?: string | null;
+    error_message?: string | null;
+    is_retryable?: boolean | null;
+}): RunDisplay;

package/dist/run-errors.js

@@ -0,0 +1,283 @@
+/**
+ * run-errors.ts — Canonical run error taxonomy.
+ *
+ * Single source of truth for all typed error codes, their human-readable
+ * messages, retryability, and display logic.
+ *
+ * VENDOR-SYNC: This file is vendored to:
+ *   - lambda/lib/run-errors.ts        (exact copy — Lambda is self-contained)
+ *   - github-action/src/run-errors.ts (exact copy — github-action can't import Supabase _shared)
+ *   - runner/src/run-errors.js        (intentional-diff: plain JS, no TypeScript)
+ *
+ * The webapp imports via `@fidel/shared/run-errors` alias → extension/src/lib/run-errors.ts.
+ * The extension copy is itself vendored from here (registered in vendor-sync.config.json).
+ *
+ * When editing this file, run `npx tsx scripts/check-vendor-sync.ts` and
+ * update all consumer copies.
+ */
+// ── Error code registry ────────────────────────────────────────────────────────
+export const RUN_ERROR_CODES = [
+    'TARGET_AUTH_WALL',
+    'TARGET_UNREACHABLE',
+    'TARGET_TIMEOUT',
+    'TARGET_CSP_BLOCKED',
+    'FIGMA_ACCESS_DENIED',
+    'FIGMA_TOKEN_EXPIRED',
+    'FIGMA_NOT_FOUND',
+    'FIGMA_RATE_LIMITED',
+    'PIPELINE_TIMEOUT',
+    'PIPELINE_ERROR',
+    'ZERO_ELEMENTS_MATCHED',
+    'PERSIST_FAILED',
+    'SESSION_EXPIRED',
+    // Phase 34-B PR 7-4: URL↔URL input validation. Each side fails its own code
+    // so the webapp's error card can highlight the correct field (matches the
+    // figmaUrl-only INVALID handling pre-34-B).
+    'INVALID_REFERENCE_URL',
+    'INVALID_TARGET_URL',
+    // Phase 34-C PR 7-4: design_system_vs_live mode prereqs.
+    // DESIGN_SYSTEM_NOT_AVAILABLE — no theme_registries row for the team's
+    // selected repo (intake never completed, or the row was deleted). Repo
+    // name omitted from the user message per security H-4 (error_message
+    // is owner-readable AND projected through get_shared_run; including the
+    // repo name would leak business intent through the share view).
+    'DESIGN_SYSTEM_NOT_AVAILABLE',
+    // Plan 021 Phase 3: caller supplied an explicit designSystemContextId that
+    // resolved to nothing (invalid id, archived, or belongs to another team).
+    // Distinct from DESIGN_SYSTEM_NOT_AVAILABLE (no theme data at all) — this
+    // means the repo/theme IS available, but the SPECIFIC brand context the
+    // caller asked for isn't. Message is repo/brand-identity-free for the same
+    // H-4 reason as DESIGN_SYSTEM_NOT_AVAILABLE. Never silently substituted for
+    // another context — the caller must re-pick.
+    'DESIGN_SYSTEM_CONTEXT_NOT_AVAILABLE',
+    // Plan 031: the theme exists (unlike DESIGN_SYSTEM_NOT_AVAILABLE) but the
+    // compatibility preflight (assessThemeValidatability in web-validate/
+    // design-system.ts) determined it can't produce a meaningful validation —
+    // unsupported UI framework (Chakra/MUI/etc.), a parse that never resolved
+    // concrete token values, or zero declared tokens. Distinct from both
+    // DESIGN_SYSTEM_NOT_AVAILABLE (no theme data at all) and
+    // DESIGN_SYSTEM_CONTEXT_NOT_AVAILABLE (theme exists, wrong brand context)
+    // — this means the RIGHT theme is present but structurally can't produce
+    // signal. Message is repo/brand-identity-free for the same H-4 reason
+    // (projected through get_shared_run to anon share viewers).
+    'DESIGN_SYSTEM_INCOMPATIBLE',
+    // W4 4c: prototype-flow validation failure — reserved for v2 flow validation.
+    // Indicates a deterministic failure during a single step of flow traversal
+    // (e.g. a transition target is missing or the step response is invalid).
+    // retryable: false — this is a structural design problem, not a transient error.
+    'FLOW_STEP_FAILED',
+    'UNKNOWN_ERROR',
+];
+export const ERROR_CODE_META = {
+    TARGET_AUTH_WALL: {
+        retryable: false,
+        userMessage: "This page is behind a login or password. Fidel can't validate protected pages yet - try a public preview URL.",
+        shortLabel: 'Login required',
+    },
+    TARGET_UNREACHABLE: {
+        retryable: false,
+        userMessage: "We couldn't reach that page. Check the URL is correct and publicly reachable from the internet.",
+        shortLabel: 'Page unreachable',
+    },
+    TARGET_TIMEOUT: {
+        retryable: true,
+        userMessage: 'The page took too long to load. Try again, or try a lighter version of the page.',
+        shortLabel: 'Page timed out',
+    },
+    TARGET_CSP_BLOCKED: {
+        retryable: false,
+        userMessage: 'The page blocked our request. It may have bot protection or strict security rules.',
+        shortLabel: 'Request blocked',
+    },
+    FIGMA_ACCESS_DENIED: {
+        retryable: false,
+        userMessage: 'Figma file not accessible. Make sure you have View or Edit access and the file is not restricted.',
+        shortLabel: 'Figma access denied',
+    },
+    FIGMA_TOKEN_EXPIRED: {
+        retryable: false,
+        userMessage: 'Your Figma session has expired. Sign out and sign back in to reconnect Figma.',
+        shortLabel: 'Figma session expired',
+    },
+    FIGMA_NOT_FOUND: {
+        retryable: false,
+        userMessage: "Figma file not found. Check the URL — the file may have been deleted or moved.",
+        shortLabel: 'Figma file not found',
+    },
+    FIGMA_RATE_LIMITED: {
+        retryable: true,
+        userMessage: 'Figma rate limit hit. Wait 1–2 minutes, then try again.',
+        shortLabel: 'Figma rate limit',
+    },
+    PIPELINE_TIMEOUT: {
+        retryable: true,
+        userMessage: 'Validation took too long to respond. Try again in a moment.',
+        shortLabel: 'Validation timed out',
+    },
+    PIPELINE_ERROR: {
+        retryable: true,
+        userMessage: "Validation failed. Try again — if it keeps failing, contact support.",
+        shortLabel: 'Validation failed',
+    },
+    ZERO_ELEMENTS_MATCHED: {
+        retryable: false,
+        userMessage: 'No page elements were found during capture. Make sure the page loads correctly and is not blank.',
+        shortLabel: 'No elements found',
+    },
+    PERSIST_FAILED: {
+        retryable: true,
+        userMessage: 'The results were generated but could not be saved. Try again in a moment.',
+        shortLabel: 'Save failed',
+    },
+    SESSION_EXPIRED: {
+        retryable: false,
+        userMessage: "This site's saved session has expired. Reconnect it to validate again.",
+        shortLabel: 'Session expired',
+    },
+    INVALID_REFERENCE_URL: {
+        retryable: false,
+        userMessage: 'The reference URL is invalid. It must start with https:// and point to a real page.',
+        shortLabel: 'Invalid reference URL',
+    },
+    INVALID_TARGET_URL: {
+        retryable: false,
+        userMessage: 'The target URL is invalid. It must start with https:// and point to a real page.',
+        shortLabel: 'Invalid target URL',
+    },
+    DESIGN_SYSTEM_NOT_AVAILABLE: {
+        retryable: false,
+        userMessage: "Design system unavailable. Connect a repo with a parsed theme to use this validation mode.",
+        shortLabel: 'Design system unavailable',
+    },
+    DESIGN_SYSTEM_CONTEXT_NOT_AVAILABLE: {
+        retryable: false,
+        userMessage: "Design system unavailable. The selected brand context is not available. Choose another or reconnect it in Settings.",
+        shortLabel: 'Brand context unavailable',
+    },
+    DESIGN_SYSTEM_INCOMPATIBLE: {
+        retryable: false,
+        userMessage: "This design system can't be checked yet. We support Tailwind + shadcn today and are adding more — reconnect a supported design system, or check back soon.",
+        shortLabel: 'Design system not supported yet',
+    },
+    FLOW_STEP_FAILED: {
+        retryable: false,
+        userMessage: 'A flow validation step failed. Check that all prototype transitions in the Figma file point to valid frames.',
+        shortLabel: 'Flow step failed',
+    },
+    UNKNOWN_ERROR: {
+        retryable: true,
+        userMessage: 'Something went wrong during validation. Try again — if it keeps failing, contact support.',
+        shortLabel: 'Unknown error',
+    },
+};
+/**
+ * Map a raw Snapshot Lambda error string to a typed RunErrorCode.
+ *
+ * Input format from Snapshot Lambda: "SNAPSHOT_ERROR:<status>:<detail>"
+ * where detail contains Chromium net::ERR_* codes.
+ */
+export function mapSnapshotErrorToCode(rawError) {
+    if (!rawError) {
+        return { code: 'TARGET_UNREACHABLE', ...meta('TARGET_UNREACHABLE') };
+    }
+    if (!rawError.includes('SNAPSHOT_ERROR')) {
+        // Not a structured snapshot error — treat as transient pipeline error
+        if (rawError.toLowerCase().includes('timeout') || rawError.toLowerCase().includes('timed out')) {
+            return { code: 'PIPELINE_TIMEOUT', ...meta('PIPELINE_TIMEOUT') };
+        }
+        return { code: 'PIPELINE_ERROR', ...meta('PIPELINE_ERROR') };
+    }
+    if (rawError.includes('ERR_INVALID_AUTH_CREDENTIALS')) {
+        return { code: 'TARGET_AUTH_WALL', ...meta('TARGET_AUTH_WALL') };
+    }
+    if (rawError.includes('ERR_NAME_NOT_RESOLVED')) {
+        return { code: 'TARGET_UNREACHABLE', message: "We couldn't find that domain. Check the URL for typos.", retryable: false };
+    }
+    if (rawError.includes('ERR_CONNECTION_REFUSED') ||
+        rawError.includes('ERR_CONNECTION_RESET') ||
+        rawError.includes('ERR_CONNECTION_CLOSED') ||
+        rawError.includes('ERR_ADDRESS_UNREACHABLE')) {
+        return { code: 'TARGET_UNREACHABLE', message: "The page didn't respond. Check that the URL is reachable from the public internet.", retryable: false };
+    }
+    if (rawError.includes('ERR_CONNECTION_TIMED_OUT') ||
+        rawError.includes('ERR_TIMED_OUT') ||
+        rawError.includes('Timeout')) {
+        return { code: 'TARGET_TIMEOUT', ...meta('TARGET_TIMEOUT') };
+    }
+    if (rawError.includes('ERR_CERT_') || rawError.includes('ERR_SSL_')) {
+        return { code: 'TARGET_UNREACHABLE', message: "The page has an SSL certificate problem we can't bypass. Check the URL or the certificate.", retryable: false };
+    }
+    if (rawError.includes('ERR_TOO_MANY_REDIRECTS')) {
+        return { code: 'TARGET_UNREACHABLE', message: 'The page is stuck in a redirect loop. Try linking directly to the final URL.', retryable: false };
+    }
+    if (rawError.includes('ERR_HTTP_RESPONSE_CODE_FAILURE') || rawError.includes('ERR_ABORTED')) {
+        return { code: 'TARGET_UNREACHABLE', message: "The page wouldn't load. Double-check the URL and make sure the page is live.", retryable: false };
+    }
+    if (rawError.includes('ERR_BLOCKED_BY_CLIENT') || rawError.includes('ERR_BLOCKED_BY_RESPONSE')) {
+        return { code: 'TARGET_CSP_BLOCKED', ...meta('TARGET_CSP_BLOCKED') };
+    }
+    if (rawError.includes('SNAPSHOT_ERROR:400')) {
+        // Lambda SSRF guard rejected the URL (private IP, localhost, etc.)
+        return { code: 'TARGET_UNREACHABLE', message: "That URL isn't reachable from the public internet. Use a live or staging URL with a public domain.", retryable: false };
+    }
+    if (rawError.includes('SNAPSHOT_ERROR:408') || rawError.includes('SNAPSHOT_ERROR:504')) {
+        return { code: 'TARGET_TIMEOUT', ...meta('TARGET_TIMEOUT') };
+    }
+    if (rawError.includes('SNAPSHOT_ERROR:422')) {
+        return { code: 'TARGET_UNREACHABLE', message: "We couldn't load that page. Double-check the URL is correct and publicly reachable.", retryable: false };
+    }
+    if (rawError.includes('SNAPSHOT_ERROR:5')) {
+        // 5xx from snapshot lambda
+        return { code: 'PIPELINE_ERROR', ...meta('PIPELINE_ERROR') };
+    }
+    return { code: 'TARGET_UNREACHABLE', message: "We couldn't load that page. Double-check the URL is correct and publicly reachable.", retryable: false };
+}
+/**
+ * Map a raw Figma fetch error string to a typed RunErrorCode.
+ */
+export function mapFigmaErrorToCode(rawError) {
+    if (rawError.includes('FIGMA_ACCESS_DENIED')) {
+        return { code: 'FIGMA_ACCESS_DENIED', ...meta('FIGMA_ACCESS_DENIED') };
+    }
+    if (rawError.includes('FIGMA_RATE_LIMIT') || rawError.includes('FIGMA_RATE_LIMITED')) {
+        return { code: 'FIGMA_RATE_LIMITED', ...meta('FIGMA_RATE_LIMITED') };
+    }
+    if (rawError.includes('FIGMA_NOT_FOUND')) {
+        return { code: 'FIGMA_NOT_FOUND', ...meta('FIGMA_NOT_FOUND') };
+    }
+    if (rawError.includes('FIGMA_SESSION_EXPIRED') || rawError.includes('FIGMA_REFRESH_FAILED') || rawError.includes('session expired')) {
+        return { code: 'FIGMA_TOKEN_EXPIRED', ...meta('FIGMA_TOKEN_EXPIRED') };
+    }
+    // Generic Figma error
+    return { code: 'FIGMA_ACCESS_DENIED', message: 'Figma file not accessible. Ensure you have View or Edit access.', retryable: false };
+}
+/**
+ * Derive a user-facing display object from a validation_runs row.
+ * Used by webapp, GitHub Action comment formatter, and the runner.
+ */
+export function resolveRunDisplay(run) {
+    if (run.status !== 'error') {
+        return { title: 'Validation complete', description: '', retryable: false };
+    }
+    const code = (run.error_code ?? 'UNKNOWN_ERROR');
+    const known = ERROR_CODE_META[code] ?? ERROR_CODE_META['UNKNOWN_ERROR'];
+    const retryable = run.is_retryable ?? known.retryable;
+    let action;
+    if (code === 'FIGMA_TOKEN_EXPIRED')
+        action = 'reconnect_figma';
+    else if (code === 'SESSION_EXPIRED')
+        action = 'reconnect_environment';
+    else if (code === 'TARGET_AUTH_WALL' || code === 'TARGET_UNREACHABLE' || code === 'TARGET_CSP_BLOCKED')
+        action = 'check_url';
+    return {
+        title: known.shortLabel,
+        description: known.userMessage,
+        retryable,
+        action,
+    };
+}
+// ── Internal helper ────────────────────────────────────────────────────────────
+function meta(code) {
+    const m = ERROR_CODE_META[code];
+    return { message: m.userMessage, retryable: m.retryable };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "//repository": [
+    "`repository` points at usefidel/fidel-contracts-publisher, the founder-only repo",
+    "that publishes this package. That repo is PRIVATE, so this link 404s for the",
+    "public \u2014 it records provenance, not a browsable source location. The package",
+    "CONTENTS are public; publication AUTHORITY is not.",
+    "The source of truth still lives in the monorepo at packages/contracts/."
+  ],
+  "name": "@usefidel/contracts",
+  "version": "0.1.0",
+  "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy only.",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./run-errors": {
+      "types": "./dist/run-errors.d.ts",
+      "import": "./dist/run-errors.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usefidel/fidel-contracts-publisher.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "check:canonical": "node scripts/check-canonical-sync.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  }
+}