@data-club/ai-hub 0.0.1

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared type definitions for the ai-hub library.
+ *
+ * Owned by `@data-club/ai-hub` per SPECIFICATIONS.md §7.1; the server package
+ * imports from here via the workspace symlink so the wire protocol (§9), the
+ * state machine (§10), and the role / user / session shapes (§11, §8) stay in
+ * exactly one place.
+ *
+ * Step 1 only defines the types — there is intentionally no runtime code in
+ * this file. Subsequent steps add reducers (Step 7), server handlers (Steps 2+),
+ * and React components (Steps 8+) that consume these.
+ *
+ * @see SPECIFICATIONS.md §7.1 — exports
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ * @see SPECIFICATIONS.md §10 — state machine
+ * @see SPECIFICATIONS.md §11 — data model
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/webcomponent/defineWebComponent.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `defineWebComponent()` — the helper every per-customer wrapper calls
+ * exactly once to ship its React tree as a `<{customer}-chat>` Web
+ * Component (§7.10).
+ *
+ * Default behavior:
+ *
+ * 1. Validates `tagName` per the WHATWG custom-element naming rules
+ *    (lowercase, contains a hyphen, not a reserved name).
+ *    https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
+ * 2. Creates an `HTMLElement` subclass:
+ *    - `connectedCallback` opens an open Shadow Root (default) or mounts
+ *      directly on the host, calls `react-dom`'s `createRoot()` against
+ *      that root, and renders `<Component />`.
+ *    - `disconnectedCallback` unmounts the React root.
+ *    - The `onConnect` / `onDisconnect` hooks fire around mount/unmount.
+ * 3. Injects the package's default CSS into the shadow root unless
+ *    `cssText` is provided (in which case the per-customer CSS is
+ *    responsible for everything).
+ * 4. Calls `customElements.define(tagName, GeneratedClass)`. Re-registration
+ *    (e.g. during hot reload) is detected and warned, not thrown — the
+ *    second registration is a no-op so dev workflows aren't blocked.
+ *
+ * @see SPECIFICATIONS.md §7.10 — defineWebComponent
+ */
+import { type ComponentType } from "react";
+import { type Root } from "react-dom/client";
+declare global {
+    interface HTMLElement {
+        /** Root used by `defineWebComponent` to track the React tree. */
+        __dcAIHubRoot?: Root;
+    }
+}
+/**
+ * Options for `defineWebComponent`.
+ */
+export interface DefineWebComponentOptions {
+    /**
+     * Render into a Shadow DOM. Default true — style isolation is what
+     * makes ai-hub safe to embed in any third-party website (§7.10).
+     * Disable only for advanced cases where the host page must reach into
+     * the chat tree (e.g. legacy print-stylesheets).
+     */
+    shadowDom?: boolean;
+    /**
+     * CSS to inject into the Shadow Root. When omitted, the library injects
+     * its bundled `default.css` (set by the consuming app's bundler via
+     * `import "@data-club/ai-hub/styles/default.css"`-style raw imports —
+     * the helper itself does not pull the file at runtime).
+     *
+     * For Step 7 the per-customer wrapper is responsible for providing
+     * either `cssText` or arranging for `default.css` to be loaded another
+     * way; the helper validates that one of the two is in place but does
+     * not embed a CSS string itself.
+     */
+    cssText?: string;
+    /**
+     * Called immediately after the React root mounts. Useful for the
+     * wrapper to attach analytics or read host-element attributes.
+     *
+     * @param host - the custom-element host.
+     */
+    onConnect?: (host: HTMLElement) => void;
+    /**
+     * Called when the custom element disconnects (just before the React root
+     * is unmounted).
+     *
+     * @param host - the custom-element host.
+     */
+    onDisconnect?: (host: HTMLElement) => void;
+}
+/**
+ * Validates a custom-element tag name per the WHATWG rules:
+ *
+ * - Starts with a lowercase ASCII letter.
+ * - Contains at least one hyphen.
+ * - Only lowercase ASCII letters, digits, hyphens, dots, and underscores.
+ * - Does not match the reserved-name list (`annotation-xml`, `color-profile`,
+ *   `font-face`, `font-face-src`, `font-face-uri`, `font-face-format`,
+ *   `font-face-name`, `missing-glyph`).
+ *
+ * @param tagName - the proposed tag name.
+ * @returns true when the name is valid.
+ */
+export declare function isValidCustomElementName(tagName: string): boolean;
+/**
+ * Registers a custom HTML element that renders `Component` inside a
+ * Shadow DOM (or directly on the host when `shadowDom: false`).
+ *
+ * Idempotent on re-registration of the same `tagName`: emits a console
+ * warning and returns without throwing (the existing element keeps
+ * working — useful during HMR).
+ *
+ * @param tagName - the custom-element tag name (must contain a hyphen).
+ * @param Component - the React component to mount.
+ * @param options - optional shadow-DOM + CSS + lifecycle settings.
+ *
+ * @example
+ * ```ts
+ * defineWebComponent("bankxyz-chat", () => <DataClubAIHub />, {
+ *   cssText: customerThemeCss,
+ * });
+ * ```
+ */
+export declare function defineWebComponent(tagName: string, Component: ComponentType, options?: DefineWebComponentOptions): void;
+//# sourceMappingURL=defineWebComponent.d.ts.map

package/dist/webcomponent/defineWebComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineWebComponent.d.ts","sourceRoot":"","sources":["../../src/webcomponent/defineWebComponent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGzD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,WAAW;QACnB,iEAAiE;QACjE,aAAa,CAAC,EAAE,IAAI,CAAC;KACtB;CACF;AAGD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACxC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAcjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,yBAA8B,GACtC,IAAI,CA+DN"}

package/dist/webcomponent/defineWebComponent.js

@@ -0,0 +1,126 @@
+/**
+ * `defineWebComponent()` — the helper every per-customer wrapper calls
+ * exactly once to ship its React tree as a `<{customer}-chat>` Web
+ * Component (§7.10).
+ *
+ * Default behavior:
+ *
+ * 1. Validates `tagName` per the WHATWG custom-element naming rules
+ *    (lowercase, contains a hyphen, not a reserved name).
+ *    https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
+ * 2. Creates an `HTMLElement` subclass:
+ *    - `connectedCallback` opens an open Shadow Root (default) or mounts
+ *      directly on the host, calls `react-dom`'s `createRoot()` against
+ *      that root, and renders `<Component />`.
+ *    - `disconnectedCallback` unmounts the React root.
+ *    - The `onConnect` / `onDisconnect` hooks fire around mount/unmount.
+ * 3. Injects the package's default CSS into the shadow root unless
+ *    `cssText` is provided (in which case the per-customer CSS is
+ *    responsible for everything).
+ * 4. Calls `customElements.define(tagName, GeneratedClass)`. Re-registration
+ *    (e.g. during hot reload) is detected and warned, not thrown — the
+ *    second registration is a no-op so dev workflows aren't blocked.
+ *
+ * @see SPECIFICATIONS.md §7.10 — defineWebComponent
+ */
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+/**
+ * Validates a custom-element tag name per the WHATWG rules:
+ *
+ * - Starts with a lowercase ASCII letter.
+ * - Contains at least one hyphen.
+ * - Only lowercase ASCII letters, digits, hyphens, dots, and underscores.
+ * - Does not match the reserved-name list (`annotation-xml`, `color-profile`,
+ *   `font-face`, `font-face-src`, `font-face-uri`, `font-face-format`,
+ *   `font-face-name`, `missing-glyph`).
+ *
+ * @param tagName - the proposed tag name.
+ * @returns true when the name is valid.
+ */
+export function isValidCustomElementName(tagName) {
+    if (typeof tagName !== "string" || tagName.length === 0)
+        return false;
+    if (!/^[a-z][a-z0-9._-]*-[a-z0-9._-]*$/.test(tagName))
+        return false;
+    const reserved = new Set([
+        "annotation-xml",
+        "color-profile",
+        "font-face",
+        "font-face-src",
+        "font-face-uri",
+        "font-face-format",
+        "font-face-name",
+        "missing-glyph",
+    ]);
+    return !reserved.has(tagName);
+}
+/**
+ * Registers a custom HTML element that renders `Component` inside a
+ * Shadow DOM (or directly on the host when `shadowDom: false`).
+ *
+ * Idempotent on re-registration of the same `tagName`: emits a console
+ * warning and returns without throwing (the existing element keeps
+ * working — useful during HMR).
+ *
+ * @param tagName - the custom-element tag name (must contain a hyphen).
+ * @param Component - the React component to mount.
+ * @param options - optional shadow-DOM + CSS + lifecycle settings.
+ *
+ * @example
+ * ```ts
+ * defineWebComponent("bankxyz-chat", () => <DataClubAIHub />, {
+ *   cssText: customerThemeCss,
+ * });
+ * ```
+ */
+export function defineWebComponent(tagName, Component, options = {}) {
+    if (!isValidCustomElementName(tagName)) {
+        throw new Error(`defineWebComponent: "${tagName}" is not a valid custom-element name. ` +
+            `Names must start with a lowercase letter, contain at least one hyphen, and use only [a-z0-9._-].`);
+    }
+    if (typeof customElements === "undefined") {
+        throw new Error("defineWebComponent: the `customElements` registry is unavailable. " +
+            "This helper must run in a browser-like environment.");
+    }
+    if (customElements.get(tagName)) {
+        // Hot-reload friendliness — registries are immutable, so we warn and
+        // bail rather than throwing.
+        // eslint-disable-next-line no-console
+        console.warn(`defineWebComponent: <${tagName}> is already registered. Skipping re-registration.`);
+        return;
+    }
+    const shadowDom = options.shadowDom !== false;
+    const cssText = options.cssText;
+    const onConnect = options.onConnect;
+    const onDisconnect = options.onDisconnect;
+    class AIHubElement extends HTMLElement {
+        connectedCallback() {
+            const target = shadowDom
+                ? this.attachShadow({ mode: "open" })
+                : this;
+            if (shadowDom && cssText) {
+                const styleEl = document.createElement("style");
+                styleEl.textContent = cssText;
+                target.appendChild(styleEl);
+            }
+            const mountNode = document.createElement("div");
+            mountNode.className = "data-club-ai-hub-mount";
+            target.appendChild(mountNode);
+            const root = createRoot(mountNode);
+            root.render(createElement(Component));
+            this.__dcAIHubRoot = root;
+            onConnect?.(this);
+        }
+        disconnectedCallback() {
+            onDisconnect?.(this);
+            const root = this.__dcAIHubRoot;
+            if (root) {
+                root.unmount();
+                delete this.__dcAIHubRoot;
+            }
+        }
+    }
+    customElements.define(tagName, AIHubElement);
+}
+//# sourceMappingURL=defineWebComponent.js.map

package/dist/webcomponent/defineWebComponent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineWebComponent.js","sourceRoot":"","sources":["../../src/webcomponent/defineWebComponent.tsx"],"names":[],"mappings":"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"}

package/dist/webcomponent/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-exports for the `webcomponent/` directory.
+ *
+ * @see SPECIFICATIONS.md §7.10 — defineWebComponent
+ */
+export { defineWebComponent, isValidCustomElementName, type DefineWebComponentOptions, } from "./defineWebComponent.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/webcomponent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webcomponent/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,yBAAyB,CAAC"}

package/dist/webcomponent/index.js

@@ -0,0 +1,7 @@
+/**
+ * Re-exports for the `webcomponent/` directory.
+ *
+ * @see SPECIFICATIONS.md §7.10 — defineWebComponent
+ */
+export { defineWebComponent, isValidCustomElementName, } from "./defineWebComponent.js";
+//# sourceMappingURL=index.js.map

package/dist/webcomponent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webcomponent/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GAEzB,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@data-club/ai-hub",
+  "version": "0.0.1",
+  "description": "React package for the data-club ai-hub: chat UI, login + change-password, admin UI, AIHub.* primitives, defineWebComponent helper, client SDK. See docs/SPECIFICATIONS.md §7.",
+  "license": "UNLICENSED",
+  "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"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./styles/default.css": "./src/styles/default.css"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@storybook/react-vite": "^10.3.6",
+    "@storybook/test-runner": "^0.24.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint-plugin-storybook": "^10.3.6",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "storybook": "^10.3.6",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.11",
+    "vitest": "^1.6.1"
+  },
+  "dependencies": {
+    "katex": "^0.16",
+    "react-markdown": "^9",
+    "rehype-katex": "^7",
+    "remark-gfm": "^4",
+    "remark-math": "^6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "dev": "vite",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "test-storybook": "test-storybook --url http://localhost:6006"
+  }
+}

package/src/__lint-canary__/step1-lint-canary.ts.disabled

@@ -0,0 +1,28 @@
+// step1-lint-canary.ts.disabled
+//
+// This file is the **deliberate lint failure** the Step 1 acceptance criteria
+// reference: "A deliberate 'exported function with no JSDoc' sample fails
+// `pnpm lint` (proves the rule is wired)." See docs/IMPLEMENTATION_PLAN.md
+// Step 1.
+//
+// HOW TO USE:
+//
+//   1. Rename this file by stripping the `.disabled` suffix:
+//        mv step1-lint-canary.ts.disabled step1-lint-canary.ts
+//   2. Run `pnpm lint`.
+//   3. ESLint MUST report `jsdoc/require-jsdoc` on `noJSDocHere`. If it
+//      doesn't, the lint plumbing is broken — fix the config before merging.
+//   4. Rename the file back (re-append `.disabled`) or delete it.
+//
+// The file is shipped suffixed-out so `pnpm lint` stays green in normal CI;
+// the suffix-flip is the "deliberate" part of "deliberate failure."
+//
+// Why a file rather than a snippet inlined in a docs file: ESLint's
+// `require-jsdoc` only runs on parsed source, not on prose. Future agents
+// who edit the lint config can flip this on, watch the rule fire, and flip
+// it off again — confirming the wiring without remembering an arbitrary
+// snippet.
+
+export function noJSDocHere(): string {
+  return "intentional regression sample — no JSDoc above this export";
+}

package/src/auth/passwordPolicy.ts

@@ -0,0 +1,75 @@
+/**
+ * Client-side mirror of the §8.5 password policy enforced server-side at
+ * `packages/ai-hub-server/src/auth/passwordPolicy.ts`.
+ *
+ * The change-password form re-runs this check before submit so the user
+ * sees the error without a round-trip; the server is authoritative — if
+ * the two ever disagree, the server wins (the form re-renders the server's
+ * error banner). The duplication is deliberate (two 5-line regex checks)
+ * because we don't want the React package to import server-only deps just
+ * to share five lines of policy.
+ *
+ * **If you tighten the policy, change it in both files** — there is a
+ * regression test that locks both modules' behavior against the same
+ * fixture set so divergence shows up as a CI failure.
+ *
+ * @see SPECIFICATIONS.md §8.5 — password complexity
+ * @see ../../../ai-hub-server/src/auth/passwordPolicy.ts — server source-of-truth
+ */
+
+/** Minimum length for a new password (§8.5). */
+export const PASSWORD_MIN_LENGTH = 8;
+
+/** Minimum distinct character categories required (§8.5). */
+export const PASSWORD_REQUIRED_CATEGORIES = 2;
+
+/** Machine-readable codes the client validator emits. */
+export type ClientPasswordPolicyErrorCode =
+  | "password_too_short"
+  | "password_too_simple";
+
+/** Result of `validatePasswordPolicyClient`. */
+export type ClientPasswordPolicyResult =
+  | { ok: true }
+  | { ok: false; code: ClientPasswordPolicyErrorCode };
+
+/**
+ * Returns whether the candidate satisfies the §8.5 policy. Used by the
+ * change-password form to disable submit / surface an inline error before
+ * issuing a request.
+ *
+ * @param password - the candidate plaintext password.
+ * @returns `{ ok: true }` or a discriminated failure code.
+ */
+export function validatePasswordPolicyClient(
+  password: string,
+): ClientPasswordPolicyResult {
+  if (password.length < PASSWORD_MIN_LENGTH) {
+    return { ok: false, code: "password_too_short" };
+  }
+  if (countCharacterCategoriesClient(password) < PASSWORD_REQUIRED_CATEGORIES) {
+    return { ok: false, code: "password_too_simple" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Counts how many of the three §8.5 categories the password matches.
+ *
+ * - letter — any Unicode letter (`\p{L}`)
+ * - digit — any Unicode number (`\p{N}`)
+ * - special — anything else that isn't whitespace (`\s`)
+ *
+ * Whitespace deliberately doesn't tick the special box — we want at least
+ * one meaningfully non-letter, non-digit character.
+ *
+ * @param password - the candidate plaintext password.
+ * @returns the count in `[0, 3]`.
+ */
+export function countCharacterCategoriesClient(password: string): number {
+  let count = 0;
+  if (/\p{L}/u.test(password)) count++;
+  if (/\p{N}/u.test(password)) count++;
+  if (/[^\p{L}\p{N}\s]/u.test(password)) count++;
+  return count;
+}