cursedbelt 2.8.0 → 3.0.0

package/src/react/schema-fields/describeSchema.ts

@@ -1,284 +0,0 @@
-/**
- * Zod schema → {@link FieldDescriptor}[] — the ONE reflection walker.
- *
- * This lived in cursedshell (`core-engine/reflection.ts` + `field-meta.ts`) and
- * moved down here for a structural reason, not a tidiness one: the descriptor
- * types, the `SchemaFields` renderer that consumes them, and now the engine
- * studio's inspector (which reflects `FeaturesByEngine` — a cursedbelt schema)
- * all live at THIS layer. A walker one layer up meant the only way to drive a
- * form from a cursedbelt schema was to write a second walker, and a second
- * walker is how "the inspector shows a checkbox for a field the schema made a
- * number" happens. cursedshell re-exports these symbols, so its public API and
- * every plugin's `field(...)` call are unchanged.
- *
- * Despite the `src/react/` path this module imports no React (see the note on
- * `types.ts`'s re-export in the root index) — it is pure over zod objects and is
- * consumed by React-free callers (`cursedshell/contract`, the catalog scanner).
- *
- * Schemas are walked via `_zod.def.type` STRING tags, never `instanceof`, so a
- * schema constructed by another package's bundled copy of zod reflects
- * identically to one built here. That is load-bearing in this monorepo: plugins,
- * cursedbelt and the generator do not share a single zod instance.
- */
-import type { z } from 'zod';
-import {
-  defaultKindFor,
-  type FieldConstraints,
-  type FieldDescriptor,
-  type FieldType,
-  type FieldUiHints,
-  humanizeFieldName,
-} from './types';
-
-/**
- * UI hints ride on zod's own `.meta()` registry under this key, co-located with
- * the schema they describe. That reaches everywhere a sibling map can't —
- * nested object properties, array items — and survives cross-package zod copies
- * because reads go through the schema's own `.meta()` method.
- *
- * The literal is `cursedshell:ui` and MUST stay that way. It is written into
- * schema metadata by every plugin that has ever called `field(...)`; renaming it
- * on the move down here would silently drop the hints off every one of them
- * (an unhinted field still renders, just with the wrong widget — the worst kind
- * of regression, because nothing fails).
- */
-export const UI_META_KEY = 'cursedshell:ui';
-
-/**
- * Attach UI field hints to a schema — the widget-mapping half of the metadata
- * contract. Wrap any field of a `configSchema` / `propsSchema`:
- *
- *   z.object({
- *     accent: field(z.string(), { kind: 'color', description: 'Accent color' }),
- *     damping: field(z.number().min(0).max(100), { kind: 'slider' }),
- *   })
- *
- * `describeSchema` resolves these into each field's descriptor; unhinted fields
- * still get a widget derived from their type.
- */
-export function field<S extends z.ZodType>(schema: S, hints: FieldUiHints): S {
-  return schema.meta({ [UI_META_KEY]: hints }) as S;
-}
-
-interface ZodDef {
-  type?: string;
-  innerType?: ZodSchemaLike;
-  element?: ZodSchemaLike;
-  shape?: Record<string, ZodSchemaLike>;
-  entries?: Record<string, string | number>;
-  values?: unknown[];
-  options?: ZodSchemaLike[];
-  defaultValue?: unknown;
-  checks?: { _zod: { def: Record<string, unknown> } }[];
-}
-
-interface ZodSchemaLike {
-  _zod: { def: ZodDef };
-  meta?: () => Record<string, unknown> | undefined;
-  shape?: Record<string, ZodSchemaLike>;
-}
-
-const defOf = (schema: ZodSchemaLike): ZodDef => schema._zod?.def ?? {};
-
-const WRAPPERS = new Set(['optional', 'nullable', 'default', 'readonly']);
-
-interface Unwrapped {
-  inner: ZodSchemaLike;
-  optional: boolean;
-  defaultValue: unknown;
-  hints: FieldUiHints | undefined;
-  description: string | undefined;
-}
-
-/** Peel Optional/Nullable/Default/Readonly wrappers, collecting the outermost
- *  hints/description/default seen on the way down. */
-function unwrap(schema: ZodSchemaLike): Unwrapped {
-  let inner = schema;
-  let optional = false;
-  let defaultValue: unknown;
-  let hints: FieldUiHints | undefined;
-  let description: string | undefined;
-  for (let depth = 0; depth < 10; depth++) {
-    const meta = inner.meta?.();
-    hints ??= meta?.[UI_META_KEY] as FieldUiHints | undefined;
-    description ??= typeof meta?.description === 'string' ? meta.description : undefined;
-    const def = defOf(inner);
-    if (!def.type || !WRAPPERS.has(def.type) || !def.innerType) break;
-    if (def.type === 'optional' || def.type === 'nullable') optional = true;
-    if (def.type === 'default' && defaultValue === undefined) {
-      defaultValue = typeof def.defaultValue === 'function' ? (def.defaultValue as () => unknown)() : def.defaultValue;
-      // A defaulted field never blocks submission — treat as optional input.
-      optional = true;
-    }
-    inner = def.innerType;
-  }
-  return { inner, optional, defaultValue, hints, description };
-}
-
-/**
- * Read the UI hints attached to a schema, unwrapping Optional / Nullable /
- * Default / Readonly wrappers (the outermost hints win — wrapping an annotated
- * schema in `.optional()` keeps its hints reachable).
- */
-export function uiHintsOf(schema: z.ZodType): FieldUiHints | undefined {
-  return unwrap(schema as unknown as ZodSchemaLike).hints;
-}
-
-function fieldTypeOf(def: ZodDef): FieldType {
-  switch (def.type) {
-    case 'string':
-      return 'string';
-    case 'number':
-    case 'int':
-      return 'number';
-    case 'boolean':
-      return 'boolean';
-    case 'enum':
-      return 'enum';
-    case 'literal':
-      return 'literal';
-    case 'array':
-    case 'tuple':
-      return 'array';
-    case 'object':
-      return 'object';
-    case 'record':
-    case 'map':
-      return 'record';
-    case 'union':
-    case 'intersection':
-      return 'union';
-    case 'date':
-      return 'date';
-    default:
-      return 'unknown';
-  }
-}
-
-function constraintsOf(def: ZodDef): FieldConstraints | undefined {
-  const checks = def.checks ?? [];
-  if (checks.length === 0) return undefined;
-  const out: FieldConstraints = {};
-  for (const check of checks) {
-    const c = check._zod?.def ?? {};
-    switch (c.check) {
-      case 'min_length':
-        out.minLength = c.minimum as number;
-        break;
-      case 'max_length':
-        out.maxLength = c.maximum as number;
-        break;
-      case 'greater_than':
-        out.min = c.value as number;
-        break;
-      case 'less_than':
-        out.max = c.value as number;
-        break;
-      case 'multiple_of':
-        out.step = c.value as number;
-        break;
-      case 'number_format':
-        if (c.format === 'safeint' || c.format === 'int32') out.int = true;
-        break;
-      case 'string_format':
-        if (c.format === 'regex' && c.pattern != null) out.pattern = String(c.pattern);
-        break;
-    }
-  }
-  return Object.keys(out).length > 0 ? out : undefined;
-}
-
-function describeType(
-  schema: ZodSchemaLike,
-  path: string,
-  name: string,
-  callerDefault?: unknown,
-): FieldDescriptor {
-  const { inner, optional, defaultValue, hints, description } = unwrap(schema);
-  const def = defOf(inner);
-  const type = fieldTypeOf(def);
-  const constraints = {
-    ...constraintsOf(def),
-    ...(hints?.min !== undefined && { min: hints.min }),
-    ...(hints?.max !== undefined && { max: hints.max }),
-    ...(hints?.step !== undefined && { step: hints.step }),
-  };
-  const hasConstraints = Object.keys(constraints).length > 0;
-  const kind =
-    hints?.kind ??
-    (type === 'number' && constraints.min !== undefined && constraints.max !== undefined
-      ? 'slider'
-      : defaultKindFor(type));
-
-  const descriptor: FieldDescriptor = {
-    path,
-    name,
-    label: hints?.label ?? (name ? humanizeFieldName(name) : 'Item'),
-    type,
-    kind,
-    optional,
-    ...(hints?.description ?? description ? { description: hints?.description ?? description } : {}),
-    ...(callerDefault !== undefined || defaultValue !== undefined
-      ? { defaultValue: callerDefault ?? defaultValue }
-      : {}),
-    ...(hasConstraints ? { constraints } : {}),
-    ...(hints?.placeholder ? { placeholder: hints.placeholder } : {}),
-    ...(hints?.rows !== undefined ? { rows: hints.rows } : {}),
-    ...(hints?.itemLabel ? { itemLabel: hints.itemLabel } : {}),
-    ...(hints?.advanced ? { advanced: true } : {}),
-  };
-
-  if (type === 'enum' && def.entries) {
-    descriptor.options = Object.values(def.entries).map((value) => ({ value: String(value) }));
-  } else if (type === 'literal' && def.values) {
-    descriptor.options = def.values.map((value) => ({ value: String(value) }));
-  } else if (type === 'array' && def.element) {
-    descriptor.item = describeType(def.element, `${path}[]`, '');
-  } else if (type === 'object') {
-    descriptor.fields = describeShape(inner, path);
-  }
-  return descriptor;
-}
-
-function orderOf(shape: Record<string, ZodSchemaLike>, name: string): number {
-  const child = shape[name];
-  if (!child) return Number.MAX_SAFE_INTEGER;
-  const { hints } = unwrap(child);
-  return hints?.order ?? Number.MAX_SAFE_INTEGER;
-}
-
-function describeShape(
-  schema: ZodSchemaLike,
-  parentPath: string,
-  defaults?: Record<string, unknown>,
-): FieldDescriptor[] {
-  const shape = schema.shape ?? defOf(schema).shape ?? {};
-  const fields = Object.entries(shape).map(([name, child]) =>
-    describeType(child, parentPath ? `${parentPath}.${name}` : name, name, defaults?.[name]),
-  );
-  // Hinted orders win; unhinted fields keep declaration order after them.
-  return fields
-    .map((field_, index) => ({ field: field_, index }))
-    .sort((a, b) => {
-      const ao = orderOf(shape, a.field.name);
-      const bo = orderOf(shape, b.field.name);
-      if (ao !== bo) return ao - bo;
-      return a.index - b.index;
-    })
-    .map(({ field: field_ }) => field_);
-}
-
-/**
- * Reflect an object schema (a plugin `configSchema`, a component `propsSchema`,
- * an engine's `FeaturesByEngine` entry) into serializable field descriptors.
- * `defaults` overrides schema-level `.default()`s at the TOP level only.
- *
- * Typed loosely on purpose: callers pass zod objects built by their OWN copy of
- * zod, whose nominal types do not unify with this package's.
- */
-export function describeSchema(
-  schema: { shape?: unknown } | z.ZodType,
-  defaults?: Record<string, unknown>,
-): FieldDescriptor[] {
-  return describeShape(schema as unknown as ZodSchemaLike, '', defaults);
-}

package/src/react/schema-fields/types.ts

@@ -1,150 +0,0 @@
-import type { FieldOption } from '../components/FieldInput';
-
-/**
- * The widget a field renders with. Leaf kinds are field-registry type keys
- * (see {@link FieldInput}'s base registry — `text`, `number`, `boolean`,
- * `select`, `color`, … plus app-registered types), so any registered control is
- * addressable from a schema. Three structural kinds are handled by
- * {@link SchemaFields} itself rather than the registry:
- *
- * - `fieldset` — a nested object rendered as a collapsible group of fields.
- * - `list` — an array rendered as add/remove/reorderable rows.
- * - `json` — the safe fallback for shapes with no structured editor (unions,
- *   records, unknowns): a validated JSON editor that never commits bad input.
- */
-export type FieldKind =
-  | 'text'
-  | 'longtext'
-  | 'number'
-  | 'slider'
-  | 'boolean'
-  | 'select'
-  | 'multiselect'
-  | 'tags'
-  | 'color'
-  | 'url'
-  | 'date'
-  | 'datetime'
-  | 'rating'
-  | 'emoji'
-  | 'password'
-  | 'code'
-  | 'combobox'
-  | 'fieldset'
-  | 'list'
-  | 'json'
-  | (string & {});
-
-/**
- * Authoring-time hints a schema owner attaches to a field (e.g. via cursedshell's
- * `field(schema, hints)`) to override what type-derivation alone would pick —
- * `kind: 'color'` on a hex string, `slider` bounds on a number, a human label.
- * Everything here is optional; a descriptor is complete without hints.
- */
-export interface FieldUiHints {
-  /** Override the derived widget (e.g. `'color'` for a hex string prop). */
-  kind?: FieldKind;
-  label?: string;
-  description?: string;
-  placeholder?: string;
-  /** Numeric bounds/step for `number`/`slider` (also derivable from schema checks). */
-  min?: number;
-  max?: number;
-  step?: number;
-  /** Rows for `longtext` textareas. */
-  rows?: number;
-  /** The noun for one row of a `list` field ("Crumb", "Column"). */
-  itemLabel?: string;
-  /** Sort weight within the parent (lower first; unhinted fields keep declaration order). */
-  order?: number;
-  /** Tuck the field under a collapsed "Advanced" group. */
-  advanced?: boolean;
-}
-
-/** The structural type of a field's value, independent of the widget rendering it. */
-export type FieldType =
-  | 'string'
-  | 'number'
-  | 'boolean'
-  | 'enum'
-  | 'literal'
-  | 'array'
-  | 'object'
-  | 'record'
-  | 'union'
-  | 'date'
-  | 'unknown';
-
-/** Validation facts extracted from a schema, used for widget config and doc pages. */
-export interface FieldConstraints {
-  min?: number;
-  max?: number;
-  step?: number;
-  minLength?: number;
-  maxLength?: number;
-  pattern?: string;
-  int?: boolean;
-}
-
-/**
- * One fully-resolved, JSON-serializable field description — the shared contract
- * between schema reflection (cursedshell's `describeSchema`) and rendering
- * ({@link SchemaFields}) / documentation. `kind` is always resolved: a hint wins,
- * otherwise it is derived from `type`.
- */
-export interface FieldDescriptor {
-  /** Dot path from the value root; an array's item descriptor appends `[]`. */
-  path: string;
-  /** Property key under the parent (`''` for an array item descriptor). */
-  name: string;
-  /** Display label: hint label, else the humanized name. */
-  label: string;
-  type: FieldType;
-  kind: FieldKind;
-  description?: string;
-  optional: boolean;
-  defaultValue?: unknown;
-  /** Choices for `enum`-typed fields (feeds select/multiselect controls). */
-  options?: FieldOption[];
-  constraints?: FieldConstraints;
-  placeholder?: string;
-  rows?: number;
-  itemLabel?: string;
-  advanced?: boolean;
-  /** Element descriptor when `type === 'array'`. */
-  item?: FieldDescriptor;
-  /** Property descriptors when `type === 'object'`. */
-  fields?: FieldDescriptor[];
-}
-
-/** "primaryColor" / "primary_color" → "Primary Color". */
-export function humanizeFieldName(name: string): string {
-  const words = name
-    .replace(/[_-]+/g, ' ')
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .trim();
-  return words.replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-/** The widget a structural type gets when no hint overrides it. */
-export function defaultKindFor(type: FieldType): FieldKind {
-  switch (type) {
-    case 'string':
-      return 'text';
-    case 'number':
-      return 'number';
-    case 'boolean':
-      return 'boolean';
-    case 'enum':
-    case 'literal':
-      return 'select';
-    case 'array':
-      return 'list';
-    case 'object':
-      return 'fieldset';
-    case 'date':
-      return 'date';
-    default:
-      return 'json';
-  }
-}

package/src/react/session/CCSessionGate.tsx

@@ -1,113 +0,0 @@
-/**
- * `CCSessionGate` — the app-wide front door for a generated app whose guard
- * instance has accounts.
- *
- * It exists because a deployed `privateMode` app had no front door at all. The
- * server 401ed every anonymous request (correctly), `AppErrorOverlay` passes
- * 401 through by design ("left to the auth surface"), and there WAS no auth
- * surface: `AuthGate` was mounted nowhere and `notifyUnauthorized` had zero call
- * sites repo-wide. A signed-out visitor to app.cursedalchemy.com got a dashboard
- * of empty widgets and no way to log in.
- *
- * `AuthGate` could not have filled the role even if mounted: it POSTs
- * `{ username, password }` as JSON, while `POST /api/guard/login` takes the
- * email as a QUERY PARAM and the password as RAW BODY BYTES (so `guardService`
- * can zeroize them — `JSON.stringify` would materialise the passphrase as a
- * second, immutable string). So this gate is built on the two pieces that
- * already speak the real wire shape:
- *
- *   * {@link AccountSignInPanel} — the SAME surface `/account` renders, so the
- *     sign-in/sign-up switch, the D33 signup gate and the `data-cc-auth`
- *     markers the browser reachability gate drives are identical wherever the
- *     door appears. A second, bespoke login form here is exactly what would let
- *     the gate and `/account` drift apart.
- *   * `CCSessionProvider`'s `signIn`/`signUp` → `accountClient` → the endpoints.
- *
- * Two conditions close it, and both are needed:
- *
- *  1. **No session** — fail-closed, so nothing renders (and no view fires a
- *     request) before there is an identity. Deterministic: no flash of a
- *     signed-out shell, no waiting on a 401 round trip.
- *  2. **The 401 signal** ({@link subscribeUnauthorized}) — for the session that
- *     dies mid-use. `CCSessionProvider` self-clears only on a `SESSION_*` code;
- *     a bare 401 from any other surface would otherwise leave `signedIn` true
- *     and strand the user on a screen of errors with no way back.
- *
- * An `?invite=<token>` in the URL opens the signup half directly — that link IS
- * the instruction to create an account, and under `signupMode: 'invite'` it is
- * the only thing that offers signup at all.
- */
-import { useEffect, useState } from 'react';
-import type { ReactNode } from 'react';
-import type { SignupMode } from '../../config/appConfig';
-import { subscribeUnauthorized } from '../authSignal';
-import { AccountSignInPanel } from '../studios/GuardAccountPanels';
-import { useCcSession } from './sessionContext';
-
-export interface CCSessionGateProps {
-  children: ReactNode;
-  /** The app's signup gate (D33) — decides whether signup is offered at all. */
-  signupMode?: SignupMode;
-  /** Heading on the sign-in card. */
-  title?: string;
-  /**
-   * Paint the door in the dark-aurora "front door" look (see {@link AuthCard}'s
-   * `aurora`) so the marketing-site → product hand-off is visually continuous.
-   * Default `true` — this IS the app's full-screen logged-out front door, the one
-   * surface that should carry the brand canvas. An app that wants the plain
-   * token-themed door instead can pass `false`.
-   */
-  aurora?: boolean;
-}
-
-export function CCSessionGate({
-  children,
-  signupMode,
-  title = 'Sign in',
-  aurora = true,
-}: CCSessionGateProps) {
-  const { signedIn, signIn, signUp } = useCcSession();
-  const [rejected, setRejected] = useState(false);
-  const [invite] = useState(() =>
-    typeof window === 'undefined'
-      ? undefined
-      : (new URLSearchParams(window.location.search).get('invite') ?? undefined),
-  );
-
-  useEffect(() => subscribeUnauthorized(() => setRejected(true)), []);
-
-  // A fresh session supersedes an earlier rejection — otherwise the gate would
-  // stay closed over a perfectly good sign-in that happened after one 401.
-  useEffect(() => {
-    if (signedIn) setRejected(false);
-  }, [signedIn]);
-
-  if (signedIn && !rejected) return <>{children}</>;
-
-  const panel = (
-    <AccountSignInPanel
-      title={title}
-      aurora={aurora}
-      {...(signupMode ? { signupMode } : {})}
-      {...(invite ? { inviteToken: invite } : {})}
-      onSignIn={({ email, password }) => signIn({ email, password })}
-      onSignUp={({ email, password, inviteToken }) =>
-        signUp({ email, password, ...(inviteToken ? { inviteToken } : {}) })
-      }
-    />
-  );
-
-  // Aurora: the AuthCard is itself the full-screen, centered, aurora-lit surface —
-  // wrapping it in a second centering box (and a max-w-sm that would clip the
-  // canvas) is wrong, so the marker rides a display-contents wrapper instead.
-  // Plain: the door has no full-screen chrome of its own, so keep the centering box.
-  return aurora ? (
-    <div data-cc-session-gate='' className='contents'>
-      {panel}
-    </div>
-  ) : (
-    <div data-cc-session-gate='' className='flex min-h-screen items-center justify-center p-6'>
-      <div className='w-full max-w-sm'>{panel}</div>
-    </div>
-  );
-}