@usefidel/contracts 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { RUN_ERROR_CODES, ERROR_CODE_META, mapSnapshotErrorToCode, mapFigmaErrorToCode, resolveRunDisplay, } from './run-errors.js';
 export type { RunErrorCode, RunErrorMeta, ErrorMapping, RunDisplay, } from './run-errors.js';
+export type { IntakeFramework, UnsupportedStack, UnsupportedReason, UnresolvedReferenceSection, UnresolvedReferenceReason, UnresolvedReference, ParsedThemeColor, ParsedThemeTypography, ParsedThemeSize, ShadcnConfig, ParsedTheme, IntakeDetection, TokenSourceKind, TokenSource, PackageRole, PackageInfo, } from './theme-intake.js';

package/dist/run-errors.d.ts

@@ -15,7 +15,7 @@
  * 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 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", "CAPABILITY_UNAVAILABLE", "PROVIDER_REQUEST_REJECTED", "UNKNOWN_ERROR"];
 export type RunErrorCode = (typeof RUN_ERROR_CODES)[number];
 export interface RunErrorMeta {
     retryable: boolean;

package/dist/run-errors.js

@@ -66,6 +66,23 @@ export const RUN_ERROR_CODES = [
     // (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',
+    // Plan G-10 follow-up: replay-provider outcomes that cannot recover by
+    // retrying. Both are deliberately provider-NEUTRAL, in name and in message.
+    // The provider, its status codes and its response bodies stay in structured
+    // logs (`replay_provider_failed`); error_message is owner-readable AND
+    // projected through get_shared_run to anon share viewers, so it must not
+    // name a vendor or describe our configuration (same H-4 reasoning as the
+    // DESIGN_SYSTEM_* codes above).
+    //
+    // CAPABILITY_UNAVAILABLE — the saved-session capability itself is not
+    // usable: credential absent, rejected, or the plan/quota is exhausted.
+    // Operator-side. retryable: false — no number of retries configures a key.
+    'CAPABILITY_UNAVAILABLE',
+    // PROVIDER_REQUEST_REJECTED — a deterministic rejection of this specific
+    // request (a 4xx that is not auth, not "gone", not rate limiting), or a 2xx
+    // whose body was structurally unusable. retryable: false — the same request
+    // will be rejected the same way.
+    'PROVIDER_REQUEST_REJECTED',
     'UNKNOWN_ERROR',
 ];
 export const ERROR_CODE_META = {
@@ -134,6 +151,16 @@ export const ERROR_CODE_META = {
         userMessage: "This site's saved session has expired. Reconnect it to validate again.",
         shortLabel: 'Session expired',
     },
+    CAPABILITY_UNAVAILABLE: {
+        retryable: false,
+        userMessage: "Validating sites that need a saved sign-in isn't available right now. This one's on us — contact support and we'll get it working.",
+        shortLabel: 'Capability unavailable',
+    },
+    PROVIDER_REQUEST_REJECTED: {
+        retryable: false,
+        userMessage: "This validation couldn't be completed. Trying again won't change the result — contact support if you need it looked at.",
+        shortLabel: 'Validation rejected',
+    },
     INVALID_REFERENCE_URL: {
         retryable: false,
         userMessage: 'The reference URL is invalid. It must start with https:// and point to a real page.',

package/dist/theme-intake.d.ts

@@ -0,0 +1,160 @@
+/**
+ * theme-intake — the wire contract for the `theme-intake` edge function's
+ * response, as consumed by the webapp.
+ *
+ * THIS FILE IS THE CONTRACT, NOT A MIRROR OF ONE FILE.
+ * ────────────────────────────────────────────────────
+ * The shape is assembled from TWO backend sources, which is why it can never be
+ * a byte-copy the way `run-errors.ts` is:
+ *
+ *   1. `supabase/functions/_shared/theme-parser/types.ts` — the ParsedTheme core.
+ *      That file also declares parser INTERNALS (RawToken's full shape,
+ *      SEMANTIC_COLOR_NAMES) which are deliberately NOT re-exported here: this
+ *      package is installable by a contractor, so it carries the wire and
+ *      nothing else.
+ *
+ *   2. `supabase/functions/theme-intake/index.ts` — adds three W3d fields to the
+ *      response at the edge boundary: `tokenSources`, `packages`,
+ *      `tokenSourcesTruncated`.
+ *
+ * Some type NAMES differ from the backend's on purpose (ColorToken →
+ * ParsedThemeColor, etc.); the FIELD names are what must stay in lockstep,
+ * because those are what cross the wire.
+ *
+ * ENFORCEMENT. `scripts/check-canonical-sync.mjs` asserts structurally that
+ * ParsedTheme here declares every field of the canonical ParsedTheme plus
+ * exactly the W3d extension fields. It runs in the monorepo merge gate and again
+ * in the publisher workflow at the pinned SHA before publishing.
+ *
+ * HISTORY. Until #591 this lived at `webapp/src/types/theme-intake.ts` with a
+ * `vendor-sync.config.json` pair pointing only at source (1). #591 moved webapp/
+ * to usefidel/fidel-web and the pair was deleted rather than migrated, leaving
+ * the contract spanning two repositories with nothing checking it. Recorded as
+ * `theme-intake-wire-contract-unguarded` (#601); this file closes it.
+ */
+export type IntakeFramework = 'next' | 'remix' | 'astro' | 'sveltekit' | 'solidstart' | 'vite' | 'react' | 'unknown';
+export type UnsupportedStack = 'chakra' | 'mui' | 'mantine' | 'antd' | 'radix-themes' | 'stitches' | 'vanilla-extract' | 'panda' | 'styled-components' | 'emotion';
+export type UnsupportedReason = 'tailwind-v3-needs-js-eval' | 'tailwind-version-unknown' | 'no-token-sources' | 'token-values-not-parsed';
+export type UnresolvedReferenceSection = 'colors' | 'fontFamily' | 'fontSize' | 'spacing' | 'borderRadius' | 'lineHeight' | 'letterSpacing' | 'fontWeight' | 'boxShadow' | 'dropShadow' | 'presets' | 'plugins' | 'other';
+export type UnresolvedReferenceReason = 'imported_value' | 'computed_expression' | 'function_call' | 'preset_referenced' | 'plugin_referenced' | 'unparseable';
+export interface UnresolvedReference {
+    section: UnresolvedReferenceSection;
+    reason: UnresolvedReferenceReason;
+    detail: string;
+}
+export interface ParsedThemeColor {
+    name: string;
+    value: string;
+    source: string;
+    layer: 'theme' | 'root';
+    resolved: string | null;
+    resolveTrail: string[];
+    /** Where the resolved value came from. */
+    resolvedFrom: 'user' | 'tailwind-default' | null;
+    /** sRGB hex (`#rrggbb`) for swatch rendering, or null when format unsupported. PR 27-06. */
+    srgb: string | null;
+}
+export interface ParsedThemeTypography {
+    name: string;
+    value: string;
+    source: string;
+    kind: 'family' | 'size' | 'weight' | 'leading' | 'tracking' | 'other';
+}
+export interface ParsedThemeSize {
+    category: string;
+    name: string;
+    /** Resolved value — `var(--X)` and `calc(var(--X) * N)` references are
+     *  walked and computed against other tokens before the row is rendered.
+     *  Falls back to the raw value when a reference can't be resolved. */
+    value: string;
+    /** Original CSS authoring value when resolution changed it. Optional —
+     *  populated only when the resolved value differs from the source. */
+    raw_value?: string;
+    source: string;
+}
+export interface ShadcnConfig {
+    style: string | null;
+    rsc: boolean | null;
+    tsx: boolean | null;
+    tailwind: {
+        config: string | null;
+        css: string | null;
+        baseColor: string | null;
+        cssVariables: boolean | null;
+        prefix: string | null;
+    } | null;
+    aliases: {
+        components: string | null;
+        utils: string | null;
+        ui: string | null;
+        lib: string | null;
+        hooks: string | null;
+    } | null;
+    iconLibrary: string | null;
+}
+export interface ParsedTheme {
+    tailwindVersion: 'v3' | 'v4' | 'unknown';
+    unsupported_reason: UnsupportedReason | null;
+    rawTokens: unknown[];
+    colors: ParsedThemeColor[];
+    typography: ParsedThemeTypography[];
+    sizes: ParsedThemeSize[];
+    files: string[];
+    unresolvedImports: string[];
+    references_default_palette: boolean;
+    shadcn: ShadcnConfig | null;
+    counts: {
+        colors: number;
+        typography: number;
+        sizes: number;
+        rawTokens: number;
+    };
+    unresolvedReferences?: UnresolvedReference[];
+    tokenSources?: TokenSource[];
+    packages?: PackageInfo[];
+    tokenSourcesTruncated?: boolean;
+}
+export interface IntakeDetection {
+    ref: string;
+    detected_at: string;
+    framework: IntakeFramework;
+    tailwind_version: 'v3' | 'v4' | 'unknown' | null;
+    has_shadcn: boolean;
+    unsupported_stack: UnsupportedStack | null;
+    files_found: string[];
+    files_missing: string[];
+    errors: {
+        path: string;
+        code: string;
+    }[];
+    hints: {
+        tailwind_config_path: string | null;
+        components_json_path: string | null;
+        globals_css_path: string | null;
+        css_token_files: string[];
+    };
+    recursive_discovery: boolean;
+    tree_truncated: boolean;
+    parsed_theme: ParsedTheme | null;
+}
+export type TokenSourceKind = 'tailwind-config' | 'tailwind-v4-css' | 'style-dictionary' | 'token-json' | 'css-variables';
+export interface TokenSource {
+    kind: TokenSourceKind;
+    /** Config file or representative file (GitHub tree path). */
+    path: string;
+    /** Owning workspace package name; null = repo root, no package ownership. */
+    packageName: string | null;
+    counts: {
+        tokens?: number;
+        customProperties?: number;
+        files?: number;
+    };
+    /** True only when values made it into parsed_theme.modes. */
+    parsed: boolean;
+}
+export type PackageRole = 'components' | 'tokens' | 'assets' | 'utilities' | 'docs' | 'unknown';
+export interface PackageInfo {
+    name: string;
+    path: string;
+    role: PackageRole;
+}

package/dist/theme-intake.js

@@ -0,0 +1,35 @@
+/**
+ * theme-intake — the wire contract for the `theme-intake` edge function's
+ * response, as consumed by the webapp.
+ *
+ * THIS FILE IS THE CONTRACT, NOT A MIRROR OF ONE FILE.
+ * ────────────────────────────────────────────────────
+ * The shape is assembled from TWO backend sources, which is why it can never be
+ * a byte-copy the way `run-errors.ts` is:
+ *
+ *   1. `supabase/functions/_shared/theme-parser/types.ts` — the ParsedTheme core.
+ *      That file also declares parser INTERNALS (RawToken's full shape,
+ *      SEMANTIC_COLOR_NAMES) which are deliberately NOT re-exported here: this
+ *      package is installable by a contractor, so it carries the wire and
+ *      nothing else.
+ *
+ *   2. `supabase/functions/theme-intake/index.ts` — adds three W3d fields to the
+ *      response at the edge boundary: `tokenSources`, `packages`,
+ *      `tokenSourcesTruncated`.
+ *
+ * Some type NAMES differ from the backend's on purpose (ColorToken →
+ * ParsedThemeColor, etc.); the FIELD names are what must stay in lockstep,
+ * because those are what cross the wire.
+ *
+ * ENFORCEMENT. `scripts/check-canonical-sync.mjs` asserts structurally that
+ * ParsedTheme here declares every field of the canonical ParsedTheme plus
+ * exactly the W3d extension fields. It runs in the monorepo merge gate and again
+ * in the publisher workflow at the pinned SHA before publishing.
+ *
+ * HISTORY. Until #591 this lived at `webapp/src/types/theme-intake.ts` with a
+ * `vendor-sync.config.json` pair pointing only at source (1). #591 moved webapp/
+ * to usefidel/fidel-web and the pair was deleted rather than migrated, leaving
+ * the contract spanning two repositories with nothing checking it. Recorded as
+ * `theme-intake-wire-contract-unguarded` (#601); this file closes it.
+ */
+export {};

package/package.json

@@ -7,8 +7,8 @@
     "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.",
+  "version": "0.3.0",
+  "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy and theme-intake wire types.",
   "license": "UNLICENSED",
   "private": false,
   "type": "module",
@@ -23,6 +23,10 @@
     "./run-errors": {
       "types": "./dist/run-errors.d.ts",
       "import": "./dist/run-errors.js"
+    },
+    "./theme-intake": {
+      "types": "./dist/theme-intake.d.ts",
+      "import": "./dist/theme-intake.js"
     }
   },
   "files": [