@usefidel/contracts 0.3.0 → 0.5.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,78 @@
+/**
+ * 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;
+/**
+ * The GitHub Actions workflow `fidel init` writes to `.github/workflows/`.
+ *
+ * Here for the same reason as the builders above: the onboarding UI shows this
+ * text for a user to copy, and `fidel init` writes it. If the two disagree, a
+ * user commits a workflow that does not match the one we told them to use.
+ *
+ * A plain constant rather than a builder because init writes it identically on
+ * both branches — the Figma and design-system flows share one workflow.
+ *
+ * The trailing newline is intentional and asserted; the file ends with one.
+ */
+export declare const WORKFLOW_YAML = "name: Design Validation\non:\n  pull_request:\n    types: [opened, synchronize]\n\npermissions:\n  contents: read\n  pull-requests: write\n  id-token: write\n\njobs:\n  fidel:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: usefidel/fidel-action@v1\n";

package/dist/onboarding-config.js

@@ -0,0 +1,113 @@
+/**
+ * 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";
+}
+/**
+ * The GitHub Actions workflow `fidel init` writes to `.github/workflows/`.
+ *
+ * Here for the same reason as the builders above: the onboarding UI shows this
+ * text for a user to copy, and `fidel init` writes it. If the two disagree, a
+ * user commits a workflow that does not match the one we told them to use.
+ *
+ * A plain constant rather than a builder because init writes it identically on
+ * both branches — the Figma and design-system flows share one workflow.
+ *
+ * The trailing newline is intentional and asserted; the file ends with one.
+ */
+export const WORKFLOW_YAML = `name: Design Validation
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+  id-token: write
+
+jobs:
+  fidel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: usefidel/fidel-action@v1
+`;

package/package.json

@@ -7,8 +7,8 @@
     "The source of truth still lives in the monorepo at packages/contracts/."
   ],
   "name": "@usefidel/contracts",
-  "version": "0.3.0",
-  "description": "Shared, code-free contracts between Fidel surfaces. Run-error taxonomy and theme-intake wire types.",
+  "version": "0.5.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": [