@usefidel/contracts 0.2.0 → 0.4.0

package/README.md

@@ -31,6 +31,19 @@ import { RUN_ERROR_CODES, resolveRunDisplay } from '@usefidel/contracts';
 import { resolveRunDisplay } from '@usefidel/contracts/run-errors';
 ```
 
+The canonical `fidel.config.json` builders live behind their own entry point, so
+importing them is a deliberate act rather than a side effect of importing the
+package:
+
+```js
+import { buildDsConfigJson, nameFromUrl } from '@usefidel/contracts/onboarding-config';
+```
+
+These are the ONE implementation of what `fidel init` writes. The CLI uses them
+to write the file and the onboarding UI uses them to render the example a user
+copies, so the two cannot drift. Their output formatting — two-space indent, key
+order, trailing newline — is part of the contract and is asserted byte for byte.
+
 Ships ESM with TypeScript declarations. No runtime dependencies.
 
 ## Versioning

package/dist/onboarding-config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Canonical `fidel.config.json` builders — the ONE implementation.
+ *
+ * WHY THIS LIVES IN THE CONTRACTS PACKAGE (F-10)
+ * ----------------------------------------------
+ * Two surfaces have to agree, byte for byte, about what `fidel init` writes:
+ *
+ *   1. the CLI, which writes the file, and
+ *   2. the onboarding UI in `usefidel/fidel-web`, which SHOWS the user that
+ *      exact text to copy.
+ *
+ * They used to agree by accident. The builders lived in
+ * `github-action/src/init.ts`, and a test in the webapp imported them across a
+ * relative path to assert the displayed example matched. The frontend split
+ * broke that path — `github-action/` stayed in the monorepo — and the test was
+ * excluded rather than deleted so the loss stayed visible (finding F-10). From
+ * then until this module existed, the CLI and the onboarding example could
+ * diverge silently, and the failure would land on a new user copying a config
+ * that no longer works.
+ *
+ * Publishing the builders makes the agreement structural instead of hopeful:
+ *
+ *     onboarding-config (here)  ->  fidel init      (writes the file)
+ *     onboarding-config (here)  ->  onboarding UI   (shows + asserts the file)
+ *
+ * NOT a shared-utils dumping ground. This module holds only the pure logic both
+ * consumers need to produce identical config bytes. It has no imports, touches
+ * no I/O, and knows nothing about prompts, filesystems, or the matching engine.
+ * Anything that does not have to be identical across both repos does not belong
+ * here — it belongs in the consumer that needs it.
+ *
+ * Exposed under its own entry point (`@usefidel/contracts/onboarding-config`)
+ * rather than the package root, so importing it is a deliberate act.
+ *
+ * FORMATTING IS PART OF THE CONTRACT. Users copy this text by hand. Two-space
+ * indent, key order, and the trailing newline are all load-bearing, and the
+ * webapp asserts them byte for byte. Changing any of them is a breaking change
+ * to what people paste into their repositories.
+ */
+/** One `designSystemChecks[]` entry. */
+export interface DsSelection {
+    name: string;
+    url: string;
+    brandKey?: string;
+}
+/**
+ * Derive a check name from a URL.
+ *
+ * Same convention as the Figma branch's frame naming: `hostname/path`, falling
+ * back to the bare hostname when the path is empty, and to the raw input when
+ * the URL will not parse (a name is better than a crash during setup).
+ */
+export declare function nameFromUrl(url: string): string;
+/**
+ * Design-system branch: write or merge `designSystemChecks[]` alongside any
+ * existing `checks[]` (Figma) entries.
+ *
+ * Never touches `checks[]` — the two arrays are independent siblings per the
+ * `_shared/app-config.ts` contract, and the runner executes each leg
+ * separately. Entries are merged, deduplicating on the (name, url) pair.
+ *
+ * `checks` is emitted FIRST when present. That ordering is observable in the
+ * output the user copies, so it is fixed, not incidental.
+ */
+export declare function buildDsConfigJson(existingRaw: Record<string, unknown> | null, dsSelections: DsSelection[]): string;

package/dist/onboarding-config.js

@@ -0,0 +1,84 @@
+/**
+ * Canonical `fidel.config.json` builders — the ONE implementation.
+ *
+ * WHY THIS LIVES IN THE CONTRACTS PACKAGE (F-10)
+ * ----------------------------------------------
+ * Two surfaces have to agree, byte for byte, about what `fidel init` writes:
+ *
+ *   1. the CLI, which writes the file, and
+ *   2. the onboarding UI in `usefidel/fidel-web`, which SHOWS the user that
+ *      exact text to copy.
+ *
+ * They used to agree by accident. The builders lived in
+ * `github-action/src/init.ts`, and a test in the webapp imported them across a
+ * relative path to assert the displayed example matched. The frontend split
+ * broke that path — `github-action/` stayed in the monorepo — and the test was
+ * excluded rather than deleted so the loss stayed visible (finding F-10). From
+ * then until this module existed, the CLI and the onboarding example could
+ * diverge silently, and the failure would land on a new user copying a config
+ * that no longer works.
+ *
+ * Publishing the builders makes the agreement structural instead of hopeful:
+ *
+ *     onboarding-config (here)  ->  fidel init      (writes the file)
+ *     onboarding-config (here)  ->  onboarding UI   (shows + asserts the file)
+ *
+ * NOT a shared-utils dumping ground. This module holds only the pure logic both
+ * consumers need to produce identical config bytes. It has no imports, touches
+ * no I/O, and knows nothing about prompts, filesystems, or the matching engine.
+ * Anything that does not have to be identical across both repos does not belong
+ * here — it belongs in the consumer that needs it.
+ *
+ * Exposed under its own entry point (`@usefidel/contracts/onboarding-config`)
+ * rather than the package root, so importing it is a deliberate act.
+ *
+ * FORMATTING IS PART OF THE CONTRACT. Users copy this text by hand. Two-space
+ * indent, key order, and the trailing newline are all load-bearing, and the
+ * webapp asserts them byte for byte. Changing any of them is a breaking change
+ * to what people paste into their repositories.
+ */
+/**
+ * Derive a check name from a URL.
+ *
+ * Same convention as the Figma branch's frame naming: `hostname/path`, falling
+ * back to the bare hostname when the path is empty, and to the raw input when
+ * the URL will not parse (a name is better than a crash during setup).
+ */
+export function nameFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const path = parsed.pathname.replace(/^\/|\/$/g, "");
+        return path ? `${parsed.hostname}/${path}` : parsed.hostname;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Design-system branch: write or merge `designSystemChecks[]` alongside any
+ * existing `checks[]` (Figma) entries.
+ *
+ * Never touches `checks[]` — the two arrays are independent siblings per the
+ * `_shared/app-config.ts` contract, and the runner executes each leg
+ * separately. Entries are merged, deduplicating on the (name, url) pair.
+ *
+ * `checks` is emitted FIRST when present. That ordering is observable in the
+ * output the user copies, so it is fixed, not incidental.
+ */
+export function buildDsConfigJson(existingRaw, dsSelections) {
+    const existingChecks = existingRaw?.checks;
+    const rawDs = existingRaw?.designSystemChecks;
+    const existingDsChecks = Array.isArray(rawDs) ? rawDs : [];
+    const merged = [...existingDsChecks];
+    for (const sel of dsSelections) {
+        if (!merged.some((c) => c.name === sel.name && c.url === sel.url)) {
+            merged.push(sel);
+        }
+    }
+    const out = {};
+    if (existingChecks !== undefined) {
+        out.checks = existingChecks;
+    }
+    out.designSystemChecks = merged;
+    return JSON.stringify(out, null, 2) + "\n";
+}

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/package.json

@@ -7,8 +7,8 @@
     "The source of truth still lives in the monorepo at packages/contracts/."
   ],
   "name": "@usefidel/contracts",
-  "version": "0.2.0",
-  "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy and theme-intake wire types.",
+  "version": "0.4.0",
+  "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy, theme-intake wire types, and the canonical fidel.config.json builders.",
   "license": "UNLICENSED",
   "private": false,
   "type": "module",
@@ -27,6 +27,10 @@
     "./theme-intake": {
       "types": "./dist/theme-intake.d.ts",
       "import": "./dist/theme-intake.js"
+    },
+    "./onboarding-config": {
+      "types": "./dist/onboarding-config.d.ts",
+      "import": "./dist/onboarding-config.js"
     }
   },
   "files": [