@orakl/shared 0.1.0

package/dist/constants/auth.constants.js

@@ -0,0 +1,94 @@
+/**
+ * Keyed by `UserPower`, so a name missing from it — or a typo in one — is a
+ * compile error rather than a power nothing reads. Two things live here per
+ * name, because both must exist for a power to be usable:
+ *
+ * - `shape` — whether the name stands at a gate or only steers the UI. Read by
+ *   the copy guard in `tests/role-ladder.test.ts`, so a gating power cannot
+ *   inherit the "reaches nothing" line by copy-paste.
+ * - `description` — what `/admin/users` prints under the toggle. Written for
+ *   the admin deciding whether to grant it: what the holder gets, and any flag
+ *   or role that applies on top. One or two short sentences.
+ */
+const POWERS = {
+    "can-access-mimic": {
+        shape: "gate",
+        description: "Opens the Mimic fixture routes in production, under /mimic. They return 404 to everyone else.",
+    },
+    "can-send-feedback": {
+        shape: "gate",
+        description: "Shows the feedback widget on every page and accepts what it sends. The FEEDBACK_WIDGET flag applies on top.",
+    },
+    "can-import-quizzes": {
+        shape: "gate",
+        description: "Opens question import at /manage/import, and the duplicate check it runs. The ENABLE_IMPORTS flag applies on top.",
+    },
+    "can-manage-features": {
+        shape: "gate",
+        description: "Opens the feature-flag dashboard at /admin/feature-flags. The admin role is needed as well.",
+    },
+    "can-add-questions": {
+        shape: "gate",
+        description: "Opens question authoring at /curator/questions, and the image upload and inline category create behind it. The curator role is needed as well.",
+    },
+    "can-manage-categories": {
+        shape: "gate",
+        description: "Opens category management at /manage/categories.",
+    },
+    "can-moderate-questions": {
+        shape: "gate",
+        description: "Opens the review queue for player-reported questions, at /manage/flagged-questions.",
+    },
+    "can-publish-questions": {
+        shape: "gate",
+        description: "Opens the authored-questions dashboard at /manage/questions and promotes questions into the shared bank, where every curator's games draw them, and withdraws them again.",
+    },
+    "is-power-user": {
+        shape: "display",
+        description: "Hides every field-description info icon, for this account only. Reaches no page and no data.",
+    },
+    "can-manage-avatars": {
+        shape: "gate",
+        description: "Opens avatar management at /manage/avatars, and the avatar sync behind it.",
+    },
+    "can-apply-for-curation": {
+        shape: "gate",
+        description: "Opens the curator application on /profile and its endpoint. The member role is needed as well.",
+    },
+    "can-1v1": {
+        shape: "gate",
+        description: "Lets a curator start a game with fewer than two other players.",
+    },
+};
+/**
+ * The runtime list of `UserPower`, which is what `/admin/users` offers and what
+ * the request schema accepts. Derived from `POWERS`, so it cannot drift from
+ * the union. See `UserPower` for what each one reaches.
+ */
+export const ALL_POWERS = Object.keys(POWERS);
+export const powerShape = (power) => POWERS[power].shape;
+/** One line for `/admin/users` to print under the toggle. */
+export const powerDescription = (power) => POWERS[power].description;
+/**
+ * Rank per role, for `hasRole`. `anonymous` and `display` share rank 0 —
+ * neither is an account, so every "is this signed in" gate compares against
+ * `member` rather than naming a role.
+ */
+export const ROLE_HIERARCHY = {
+    anonymous: 0,
+    display: 0,
+    member: 1,
+    curator: 2,
+    admin: 3,
+};
+export const ANON_USER = {
+    id: "anon",
+    email: null,
+    nickname: null,
+    avatar: null,
+    role: "anonymous",
+    powers: [],
+    lobbyCode: null,
+    emailVerified: false,
+    sid: null,
+};

package/dist/constants/feature-flags.constants.d.ts

@@ -0,0 +1,138 @@
+import type { UserPower, UserRole } from "../types/auth.ts";
+type FeatureFlagRule = {
+    percentageOfUsers?: number;
+    userRoles?: UserRole[];
+} & ({
+    percentageOfUsers: number;
+} | {
+    userRoles: UserRole[];
+});
+/**
+ * Which mechanism governs a flag (map #859, decision 1):
+ * - `build` — resolved at build time; disabled features leave the bundle
+ * - `db` — one live on/off for everyone, toggled from the admin dashboard
+ * - `role` — live on/off plus role targeting
+ *
+ * A `build` flag is XOR with this registry (decision 5): it lives as a
+ * `__FEATURE_*__` define in `build-flags.mjs`, never as an entry here, so the
+ * tier exists for the dashboard to render build flags as read-only status.
+ */
+export type FlagTier = "build" | "db" | "role";
+/**
+ * A flag's code-side description. The registry is the source of truth for which
+ * flags exist; the `feature_flags` table carries live overrides on top.
+ *
+ * `roles` pairs only with a boolean default — a rule array carries its own role
+ * restrictions, so the two forms are kept mutually exclusive.
+ */
+/** The tiers a registry entry may carry — `build` is XOR with this registry. */
+type RuntimeFlagTier = Exclude<FlagTier, "build">;
+export type FlagDescriptor = {
+    tier: RuntimeFlagTier;
+    /** Code default. */
+    default: boolean;
+    description: string;
+    /** Roles the flag is limited to while its default is `true`. */
+    roles?: UserRole[];
+    /**
+     * A power this flag composes with (map #859, decision 3). `canUseFeature`
+     * requires both; the flag alone never grants the capability.
+     */
+    power?: UserPower;
+} | {
+    tier: RuntimeFlagTier;
+    /**
+     * Code-only default: a rule list evaluated per user (percentage rollout
+     * and/or role restrictions, which live inside the rules). It answers per
+     * user rather than globally, so the dashboard renders it read-only —
+     * a database override would replace the rule, not adjust it. Change the
+     * rules here, or pin the whole flag with `FEATURE_FLAG_<NAME>`.
+     *
+     * No registered flag uses this form today; the evaluator and its tests
+     * stay in place for the next rollout that needs one.
+     */
+    default: FeatureFlagRule[];
+    description: string;
+    roles?: never;
+    /** As above — a code rule can compose with a power just the same. */
+    power?: UserPower;
+};
+/**
+ * Feature flag registry — source of truth for which flags exist, their tier,
+ * default, description and optional role targeting.
+ *
+ * Resolution order stays env → DB → code:
+ * set FEATURE_FLAG_<NAME>=true/false to override any flag per environment.
+ */
+/** Shown by both import surfaces, so a copy edit cannot reach only one. */
+export declare const IMPORTS_REFUSED = "Importing questions is not available to you.";
+export declare const FLAG_REGISTRY: {
+    FEEDBACK_WIDGET: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    ENABLE_IMPORTS: {
+        tier: "db";
+        default: true;
+        description: string;
+        power: "can-import-quizzes";
+    };
+    PLAYER_HISTORY: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    CURATOR_HISTORY: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    SOLO_LEADERBOARDS: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    QUIZ_SCORING_MODES: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    QUIZ_ACCESS_MODES: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    QUIZ_MAX_PLAYERS: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    QUIZ_PRESETS: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    IMAGE_QUIZ_CATEGORY: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    BADGE_DISPLAY: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+    ROLE_SELECTION: {
+        tier: "db";
+        default: false;
+        description: string;
+    };
+};
+export type FeatureFlagName = keyof typeof FLAG_REGISTRY;
+/**
+ * Code defaults keyed by flag name, derived from the registry. Kept as the
+ * shape `evaluateFeatureFlag` consumes.
+ */
+export declare const FEATURE_FLAGS: { [K in FeatureFlagName]: (typeof FLAG_REGISTRY)[K]["default"]; };
+export {};

package/dist/constants/feature-flags.constants.js

@@ -0,0 +1,119 @@
+/**
+ * Feature flag registry — source of truth for which flags exist, their tier,
+ * default, description and optional role targeting.
+ *
+ * Resolution order stays env → DB → code:
+ * set FEATURE_FLAG_<NAME>=true/false to override any flag per environment.
+ */
+/** Shown by both import surfaces, so a copy edit cannot reach only one. */
+export const IMPORTS_REFUSED = "Importing questions is not available to you.";
+export const FLAG_REGISTRY = {
+    FEEDBACK_WIDGET: {
+        tier: "db",
+        default: false,
+        description: "Click-to-annotate feedback widget (local dev + PR previews)",
+    },
+    // Curator question import (map #859, decision 3). Composed with the
+    // `can-import-quizzes` power — the flag is the global switch, the power says
+    // who. Defaults on so the cutover takes nobody's access away. Turning it off
+    // stops imports for everyone, power-holders included, but takes up to the
+    // 5-minute resolution TTL to reach every process (decision 4) — it is not an
+    // instant kill switch.
+    ENABLE_IMPORTS: {
+        tier: "db",
+        default: true,
+        description: "Curator question import",
+        power: "can-import-quizzes",
+    },
+    // Player history (map #859, decision 18). `CONTEXT.md` names Player history
+    // and Game history as separate things, so they carry separate flags. Off
+    // hides every route into a player's own record and refuses the pages
+    // themselves; the runs, stats and badges behind them are untouched, and
+    // account export still returns them — export is a data right, not a feature
+    // (decision 19).
+    PLAYER_HISTORY: {
+        tier: "db",
+        default: false,
+        description: "Player history — a player's own runs, stats and badges",
+    },
+    // Game history (map #859, decision 18) — the curator's record of nights they
+    // ran. Off hides the History link and refuses both the pages and the
+    // endpoints behind them. The second save-as-preset entry lives on a session
+    // page and goes with it; the create form keeps its own (decision 23).
+    CURATOR_HISTORY: {
+        tier: "db",
+        default: false,
+        description: "Game history — a curator's record of the nights they ran",
+    },
+    // The persistent solo boards (map #859, decision 22): the rankings page, its
+    // endpoint and the share card. The end-of-game ceremony standings are how a
+    // Game ends rather than a leaderboard feature, and are not gated here.
+    SOLO_LEADERBOARDS: {
+        tier: "db",
+        default: false,
+        description: "Oracle rankings — the persistent solo leaderboards",
+    },
+    // The four curator create-form options (map #859, decisions 13, 16, 21).
+    // Each removes one control from the form and pins its value on the server:
+    // the form is reachable without the page, so the hidden control is never
+    // the guard. A value submitted for a gated field is ignored rather than
+    // refused — the curator was not offered the choice, so there is no mistake
+    // to report back.
+    QUIZ_SCORING_MODES: {
+        tier: "db",
+        default: false,
+        description: "Scoring picker on the create form; off pins classic scoring",
+    },
+    QUIZ_ACCESS_MODES: {
+        tier: "db",
+        default: false,
+        description: "Access picker on the create form; off pins every lobby open",
+    },
+    QUIZ_MAX_PLAYERS: {
+        tier: "db",
+        default: false,
+        description: "Max-players field on the create form; off leaves lobbies uncapped",
+    },
+    QUIZ_PRESETS: {
+        tier: "db",
+        default: false,
+        description: "Saved quizzes — save, list and apply. Stored rows survive while off",
+    },
+    // Interim release measure (map #859, decision 10): hides the seeded
+    // "Image Quiz" category from the surfaces that pick a category to play or
+    // author into, while the image-upload model redesign waits in Fog. Defaults
+    // off — hiding it is the point — and never touches the question data, so
+    // turning it back on restores the category as it was.
+    IMAGE_QUIZ_CATEGORY: {
+        tier: "db",
+        default: false,
+        description: "Image Quiz category in category pickers",
+    },
+    // Badge display (map #928, decision 1). Off hides badges on every surface —
+    // multiplayer and solo results Accolades, game and solo history detail, the
+    // aggregate tally — while computation and persistence stay untouched.
+    BADGE_DISPLAY: {
+        tier: "db",
+        default: false,
+        description: "Badge display — Accolades on results and badges in history",
+    },
+    // Role selection (map #928, decisions 2, 8, 9). Off hides the setup-page
+    // role picker (every joiner is a player), the mid-tournament roles page and
+    // its "New quiz" trigger (the curator returns players to the lobby
+    // directly instead), and the observer tiles/badges on results and the
+    // curator display. Server-side observer answer/emote refusals stay live
+    // regardless.
+    ROLE_SELECTION: {
+        tier: "db",
+        default: false,
+        description: "Role selection — the observer/player picker between games",
+    },
+};
+/**
+ * Code defaults keyed by flag name, derived from the registry. Kept as the
+ * shape `evaluateFeatureFlag` consumes.
+ */
+export const FEATURE_FLAGS = Object.fromEntries(Object.entries(FLAG_REGISTRY).map(([name, { default: value }]) => [
+    name,
+    value,
+]));

package/dist/constants/font.constants.d.ts

@@ -0,0 +1,9 @@
+import type { FontPreference } from "../font.ts";
+export declare const FONT_COOKIE = "orakl-font";
+export declare const DEFAULT_FONT: FontPreference;
+/** All selectable typeface preferences. */
+export declare const FONT_PREFERENCES: FontPreference[];
+/** Human-readable labels. */
+export declare const FONT_LABELS: Record<FontPreference, string>;
+/** Short descriptions for the picker UI. */
+export declare const FONT_DESCRIPTIONS: Record<FontPreference, string>;

package/dist/constants/font.constants.js

@@ -0,0 +1,14 @@
+export const FONT_COOKIE = "orakl-font";
+export const DEFAULT_FONT = "default";
+/** All selectable typeface preferences. */
+export const FONT_PREFERENCES = ["default", "dyslexic"];
+/** Human-readable labels. */
+export const FONT_LABELS = {
+    default: "Default",
+    dyslexic: "Dyslexia-friendly",
+};
+/** Short descriptions for the picker UI. */
+export const FONT_DESCRIPTIONS = {
+    default: "Albertus Nova and Geist",
+    dyslexic: "OpenDyslexic, weighted to anchor letters",
+};

package/dist/constants/lobby.constants.d.ts

@@ -0,0 +1,2 @@
+export declare const ADJECTIVES: string[];
+export declare const NOUNS: string[];