@jumentix/cli-init 0.0.0

package/templates/frontend/src/contracts/apiClient.ts

@@ -0,0 +1,48 @@
+import { RestApiClient } from '@jumentix/sdk-rest-client';
+
+import openApi from './openapi.json';
+
+/**
+ * The OAS document is the only backend reference this app knows
+ * (requirement 136): bundled at build time by scripts/sync-contracts.mjs
+ * and injected into the SDK, whose default loader reads the spec from disk
+ * and therefore cannot run in the browser.
+ *
+ * The SDK parses URLs with `new URL(...)`, so the base must be absolute:
+ * same-origin in the browser (vite proxies /api to the standalone backend
+ * in dev), an explicit http URL everywhere else (tests, SSR).
+ */
+const defaultBaseUrl = (): string => {
+  const fromEnv = import.meta.env?.VITE_API_BASE_URL as string | undefined;
+  if (fromEnv) {
+    return fromEnv;
+  }
+  if (typeof window !== 'undefined' && window.location?.origin) {
+    return `${window.location.origin}/api/1.0.0`;
+  }
+  return 'http://localhost:3001/api/1.0.0';
+};
+
+export const createApiClient = (baseUrl: string = defaultBaseUrl()): RestApiClient => {
+  const injectBundledSpec = () => ({ openApi: openApi as Record<string, unknown> });
+  return new RestApiClient(baseUrl, injectBundledSpec);
+};
+
+/**
+ * Shared client (JUM-765): every store talks to the server through this one
+ * instance, so the NetworkActivity widget sees all UI↔server traffic through
+ * a single subscription to the SDK's request lifecycle events.
+ */
+let sharedClient: RestApiClient | undefined;
+
+export const getSharedApiClient = (): RestApiClient => {
+  if (!sharedClient) {
+    sharedClient = createApiClient();
+  }
+  return sharedClient;
+};
+
+/** Test hook: resets the singleton so suites do not leak subscriptions. */
+export const resetSharedApiClient = (): void => {
+  sharedClient = undefined;
+};

package/templates/frontend/src/contracts/appOperations.ts

@@ -0,0 +1,74 @@
+import openApi from './openapi.json';
+
+/**
+ * Application-level operation map (JUM-780). The shell (auth, profile, nav)
+ * used to hardcode operationIds such as `getAll` and `getOneById` in five
+ * files; a generated app for another domain renamed them in the spec and
+ * the UI silently hid everything because `can()` fails closed on unknown
+ * ids. The map is one object, overridable, and validated against the
+ * bundled OAS at boot: a missing operation is a visible error, not a blank
+ * screen.
+ */
+export interface AppOperations {
+  auth: { login: string; register: string; logout: string };
+  profile: { get: string; update: string; updatePassword: string };
+}
+
+export const DEFAULT_APP_OPERATIONS: AppOperations = {
+  auth: { login: 'login', register: 'register', logout: 'logout' },
+  profile: { get: 'getOneById', update: 'update', updatePassword: 'updatePassword' }
+};
+
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
+
+const declaredOperationIds = (): Set<string> => {
+  const ids = new Set<string>();
+  type Paths = Record<string, Record<string, { operationId?: string }>>;
+  const paths = (openApi as { paths?: Paths }).paths ?? {};
+  for (const pathItem of Object.values(paths)) {
+    for (const operation of Object.values(pathItem)) {
+      if (operation && typeof operation === 'object' && operation.operationId) ids.add(operation.operationId);
+    }
+  }
+  return ids;
+};
+
+/**
+ * Returns the ids each missing from the contract, keyed by their dotted path
+ * (`profile.get`). Empty when the map is fully declared.
+ */
+export const validateAppOperations = (
+  operations: AppOperations,
+  declared: Set<string> = declaredOperationIds()
+): string[] => {
+  const missing: string[] = [];
+  for (const [group, entries] of Object.entries(operations)) {
+    for (const [key, id] of Object.entries(entries as Record<string, string>)) {
+      if (!declared.has(id)) missing.push(`${group}.${key} → "${id}"`);
+    }
+  }
+  return missing;
+};
+
+export const resolveAppOperations = (overrides?: DeepPartial<AppOperations>): AppOperations => ({
+  auth: { ...DEFAULT_APP_OPERATIONS.auth, ...(overrides?.auth ?? {}) },
+  profile: { ...DEFAULT_APP_OPERATIONS.profile, ...(overrides?.profile ?? {}) }
+});
+
+let active: AppOperations = resolveAppOperations();
+
+/** Installs the map for the app; throws listing every id the OAS does not declare. */
+export const configureAppOperations = (overrides?: DeepPartial<AppOperations>): AppOperations => {
+  const next = resolveAppOperations(overrides);
+  const missing = validateAppOperations(next);
+  if (missing.length > 0) {
+    throw new Error(
+      `appOperations: the bundled OAS declares no operation for ${missing.join(', ')}. `
+        + 'Regenerate src/contracts/openapi.json or override the ids in configureAppOperations().'
+    );
+  }
+  active = next;
+  return active;
+};
+
+export const appOperations = (): AppOperations => active;

package/templates/frontend/src/contracts/errors.ts

@@ -0,0 +1,51 @@
+import { t } from '@/i18n';
+
+/**
+ * Human-readable mapping of the SDK's `REST request failed: <status> <body>`
+ * errors (JUM-765). Backend error messages are preserved when present;
+ * generic texts come from the i18n table (JUM-780).
+ */
+export const formatApiError = (error: unknown): string => {
+  const message = error instanceof Error ? error.message : String(error);
+  const match = /REST request failed: (\d{3})\s*(.*)/s.exec(message);
+  if (!match) {
+    return message;
+  }
+  const status = Number(match[1]);
+  let backendMessage = '';
+  try {
+    const parsed = JSON.parse(match[2] || '{}') as { message?: string };
+    backendMessage = parsed.message ?? '';
+  } catch {
+    backendMessage = match[2]?.slice(0, 120) ?? '';
+  }
+
+  switch (status) {
+    case 400:
+      return backendMessage || t('error.badRequest');
+    case 401:
+      return t('error.unauthorized');
+    case 403:
+      return t('error.forbidden');
+    case 404:
+      return t('error.notFound');
+    case 409:
+      return backendMessage || t('error.conflict');
+    default:
+      if (status >= 500) {
+        return t('error.server');
+      }
+      return backendMessage || t('error.generic', { status });
+  }
+};
+
+export const isNotFoundError = (error: unknown): boolean => (
+  error instanceof Error && /REST request failed: 404(\s|$)/.test(error.message)
+);
+
+/** Status code of an SDK error, or undefined when it is not an HTTP failure. */
+export const apiErrorStatus = (error: unknown): number | undefined => {
+  const message = error instanceof Error ? error.message : String(error);
+  const match = /REST request failed: (\d{3})/.exec(message);
+  return match ? Number(match[1]) : undefined;
+};

package/templates/frontend/src/contracts/formSchema.ts

@@ -0,0 +1,202 @@
+import openApi from './openapi.json';
+
+/**
+ * Runtime form engine over the bundled OAS (JUM-766). The app parses the
+ * OpenAPI JSON at runtime and forms are built by iterating the schema's
+ * properties — nothing about a field is hardcoded, so a spec change (a
+ * renamed field, a new maxLength, a new enum option) renders correctly on
+ * the next load without touching component code.
+ */
+
+export interface FieldDescriptor {
+  name: string;
+  type: string;
+  format?: string;
+  required: boolean;
+  minLength?: number;
+  maxLength?: number;
+  enum?: string[];
+  pattern?: string;
+  default?: unknown;
+  nullable?: boolean;
+  description?: string;
+  example?: string;
+  xValidation?: Record<string, unknown>;
+  /** `x-relation` (JUM-787): FK to another entity; list op comes from `<Entity>ArrayOf`. */
+  relation?: {
+    field: string;
+    entity: string;
+    match: string;
+    display: string;
+    kind: 'belongsTo' | 'hasMany';
+  };
+  /** JSON Schema `title`: the label fallback before humanizing the property name (JUM-780). */
+  title?: string;
+  /** `x-label` (JUM-780): localized labels keyed by locale (`en`, `pt-BR`). */
+  xLabel?: Record<string, string>;
+}
+
+interface RawSchema {
+  type?: string;
+  format?: string;
+  properties?: Record<string, RawSchema>;
+  required?: string[];
+  $ref?: string;
+  items?: RawSchema;
+  allOf?: RawSchema[];
+  [facet: string]: unknown;
+}
+
+const document = openApi as {
+  components?: { schemas?: Record<string, RawSchema> };
+  paths?: Record<string, Record<string, RawSchema & {
+    operationId?: string;
+    responses?: Record<string, unknown>;
+  }>>;
+};
+
+export interface EntityRelation {
+  field: string;
+  entity: string;
+  match: string;
+  display: string;
+  kind: 'belongsTo' | 'hasMany';
+}
+
+/** Schema-level `x-primary-key`, default `id`. */
+export const entityPrimaryKey = (entity: string): string => {
+  const schema = document.components?.schemas?.[entity];
+  const key = schema?.['x-primary-key'];
+  return typeof key === 'string' && key.length > 0 ? key : 'id';
+};
+
+const asRelation = (property: RawSchema, name: string): EntityRelation | undefined => {
+  const raw = property['x-relation'] as Partial<EntityRelation> | undefined;
+  if (!raw || typeof raw !== 'object' || !raw.entity) return undefined;
+  return {
+    field: raw.field ?? name,
+    entity: raw.entity,
+    match: raw.match ?? entityPrimaryKey(raw.entity),
+    display: raw.display ?? 'name',
+    kind: raw.kind === 'hasMany' ? 'hasMany' : 'belongsTo'
+  };
+};
+
+const responseSchemaName = (operation: RawSchema): string | undefined => {
+  const ok = (operation.responses as Record<string, any> | undefined)?.['200'];
+  const ref = ok?.content?.['application/json']?.schema?.$ref as string | undefined;
+  return ref?.replace('#/components/schemas/', '');
+};
+
+/** List operation whose 200 schema is `<Entity>ArrayOf`. */
+export const listOperationForEntity = (entity: string): string | undefined => {
+  const expected = `${entity}ArrayOf`;
+  for (const pathItem of Object.values(document.paths ?? {})) {
+    for (const operation of Object.values(pathItem)) {
+      if (operation?.operationId && responseSchemaName(operation) === expected) {
+        return operation.operationId;
+      }
+    }
+  }
+  return undefined;
+};
+
+/** GET-by-id whose 200 schema is the entity itself (not the list envelope). */
+export const getOperationForEntity = (entity: string): string | undefined => {
+  for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+    if (path.includes('{')) {
+      const operation = pathItem.get;
+      if (operation?.operationId && responseSchemaName(operation) === entity) {
+        return operation.operationId;
+      }
+    }
+  }
+  return undefined;
+};
+
+/** Resolves a local $ref (#/components/schemas/X) to its schema. */
+const resolveRef = (schema: RawSchema): RawSchema => {
+  if (!schema.$ref) {
+    return schema;
+  }
+  const name = schema.$ref.replace('#/components/schemas/', '');
+  const target = document.components?.schemas?.[name];
+  if (!target) {
+    throw new Error(`formSchema: unresolved $ref ${schema.$ref}`);
+  }
+  return resolveRef(target);
+};
+
+/** Merges allOf parts into a single property/required view. */
+const flattenAllOf = (schema: RawSchema): RawSchema => {
+  if (!schema.allOf) {
+    return schema;
+  }
+  return schema.allOf.reduce<RawSchema>((acc, part) => {
+    const resolved = flattenAllOf(resolveRef(part));
+    return {
+      ...acc,
+      ...resolved,
+      properties: { ...acc.properties, ...resolved.properties },
+      required: [...(acc.required ?? []), ...(resolved.required ?? [])]
+    };
+  }, {});
+};
+
+export const resolveSchema = (name: string): RawSchema => {
+  const schema = document.components?.schemas?.[name];
+  if (!schema) {
+    throw new Error(`formSchema: schema "${name}" not declared in the bundled OAS`);
+  }
+  return flattenAllOf(resolveRef(schema));
+};
+
+/** Iterates the schema properties in declaration order, one descriptor per field. */
+export const fieldDescriptors = (schemaName: string): FieldDescriptor[] => {
+  const schema = resolveSchema(schemaName);
+  const required = schema.required ?? [];
+
+  return Object.entries(schema.properties ?? {})
+    // `x-hide: true` (JUM-769): the property stays in the contract (defaults
+    // apply server-side) but never renders in OAS-driven forms.
+    .filter(([, rawProperty]) => resolveRef(rawProperty)['x-hide'] !== true)
+    .map(([name, rawProperty]) => {
+      const property = resolveRef(rawProperty);
+      return {
+        name,
+        type: property.type ?? 'string',
+        format: property.format as string | undefined,
+        required: required.includes(name),
+        minLength: property.minLength as number | undefined,
+        maxLength: property.maxLength as number | undefined,
+        enum: property.enum as string[] | undefined,
+        pattern: property.pattern as string | undefined,
+        default: property.default,
+        nullable: property.nullable as boolean | undefined,
+        description: property.description as string | undefined,
+        example: property.example !== undefined ? String(property.example) : undefined,
+        xValidation: property['x-validation'] as Record<string, unknown> | undefined,
+        relation: asRelation(property, name),
+        title: property.title as string | undefined,
+        xLabel: property['x-label'] as Record<string, string> | undefined
+      };
+    });
+};
+
+/**
+ * Descriptors for the items of an array-of-objects field (JUM-772): resolves
+ * `properties[field].items.$ref` to the item schema and iterates it. Returns
+ * undefined for scalar arrays or fields without a $ref — those are not
+ * object editors.
+ */
+export const arrayItemDescriptors = (
+  schemaName: string,
+  fieldName: string
+): FieldDescriptor[] | undefined => {
+  const schema = resolveSchema(schemaName);
+  const property = schema.properties?.[fieldName];
+  const itemRef = property?.items?.$ref;
+  if (!itemRef) return undefined;
+  const itemSchema = itemRef.replace('#/components/schemas/', '');
+  return fieldDescriptors(itemSchema).filter((d) => d.name !== 'id');
+};

package/templates/frontend/src/contracts/labels.ts

@@ -0,0 +1,41 @@
+import type { FieldDescriptor } from '@/contracts/formSchema';
+import { currentLocale } from '@/i18n';
+
+/**
+ * Field labels from the contract (JUM-780). Order of precedence:
+ *
+ * 1. `x-label[locale]` (then `x-label.en`) — the localized label the OAS declares;
+ * 2. `title` — JSON Schema's own display name;
+ * 3. the humanized property name (`firstName` → "First name").
+ *
+ * `description` is deliberately *not* a label any more: it is help text. The
+ * previous behaviour rendered "Organization id for tenant users (admin/user)"
+ * as a form label, which is documentation, not a caption.
+ */
+export const humanize = (name: string): string => {
+  const spaced = name
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .trim();
+  if (!spaced) return name;
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+};
+
+export const fieldLabel = (
+  descriptor: Pick<FieldDescriptor, 'name' | 'title' | 'xLabel'>,
+  overrides?: Record<string, string>
+): string => {
+  const override = overrides?.[descriptor.name];
+  if (override) return override;
+  const locale = currentLocale();
+  const localized = descriptor.xLabel?.[locale] ?? descriptor.xLabel?.en;
+  if (localized) return localized;
+  if (descriptor.title) return descriptor.title;
+  return humanize(descriptor.name);
+};
+
+/** Help text: the OAS description, shown under the control, never as its label. */
+export const fieldHelp = (descriptor: Pick<FieldDescriptor, 'description'>): string | undefined => (
+  descriptor.description
+);

package/templates/frontend/src/contracts/listSchema.ts

@@ -0,0 +1,115 @@
+import openApi from './openapi.json';
+
+/**
+ * List capabilities from the contract (JUM-778). A list operation may carry
+ * `x-list-capabilities`; when it does, X-CRUD asks the server for pages and
+ * renders sort/filter/search affordances only for the fields declared there.
+ * When it does not, the kit keeps the in-memory path over the whole result
+ * — the choice comes from the contract, never from component config.
+ */
+export type ListFilterKind = 'text' | 'enum' | 'boolean' | 'date' | 'uuid' | 'number';
+
+export interface ListCapabilities {
+  sortable: string[];
+  filterable: Record<string, ListFilterKind>;
+  searchable: string[];
+  defaultSize: number;
+  maxSize: number;
+}
+
+interface RawOperation {
+  operationId?: string;
+  'x-list-capabilities'?: Partial<ListCapabilities>;
+}
+
+const document = openApi as { paths?: Record<string, Record<string, RawOperation>> };
+
+const operations = (): Record<string, RawOperation> => {
+  const map: Record<string, RawOperation> = {};
+  for (const pathItem of Object.values(document.paths ?? {})) {
+    for (const operation of Object.values(pathItem)) {
+      if (operation && typeof operation === 'object' && operation.operationId) {
+        map[operation.operationId] = operation;
+      }
+    }
+  }
+  return map;
+};
+
+const byOperation = operations();
+
+export const listCapabilities = (operationId: string): ListCapabilities | undefined => {
+  const raw = byOperation[operationId]?.['x-list-capabilities'];
+  if (!raw) return undefined;
+  return {
+    sortable: raw.sortable ?? [],
+    filterable: raw.filterable ?? {},
+    searchable: raw.searchable ?? [],
+    defaultSize: raw.defaultSize ?? 30,
+    maxSize: raw.maxSize ?? 100
+  };
+};
+
+/** One page of a server-side list, as the OAS `*ArrayOf` envelope declares it. */
+export interface ListPage<T> {
+  result: T[];
+  page: number;
+  size: number;
+  total: number;
+}
+
+/** Wire form of the list query the SDK sends (`filter` is base64 JSON). */
+export interface ListQuery {
+  page?: number;
+  size?: number;
+  sort?: string;
+  q?: string;
+  filter?: Record<string, unknown>;
+  includeDeleted?: boolean;
+}
+
+const toBase64 = (value: string): string => {
+  if (typeof btoa === 'function') {
+    return btoa(unescape(encodeURIComponent(value)));
+  }
+  return Buffer.from(value, 'utf8').toString('base64');
+};
+
+export const toQueryParams = (query: ListQuery): Record<string, string | number> => {
+  const params: Record<string, string | number> = {};
+  if (query.page !== undefined) params.page = query.page;
+  if (query.size !== undefined) params.size = query.size;
+  if (query.sort) params.sort = query.sort;
+  if (query.q) params.q = query.q;
+  if (query.filter && Object.keys(query.filter).length > 0) {
+    params.filter = toBase64(JSON.stringify(query.filter));
+  }
+  if (query.includeDeleted) params.includeDeleted = 'true';
+  return params;
+};
+
+/**
+ * Normalizes what the server returned: the envelope when the contract
+ * declares one, or a bare array from an operation that predates JUM-777.
+ */
+export const asListPage = <T>(
+  response: unknown,
+  fallback: { page: number; size: number }
+): ListPage<T> => {
+  if (Array.isArray(response)) {
+    return {
+      result: response as T[],
+      page: 1,
+      size: response.length || fallback.size,
+      total: response.length
+    };
+  }
+  const envelope = (response ?? {}) as Partial<ListPage<T>>;
+  const result = Array.isArray(envelope.result) ? envelope.result : [];
+  return {
+    result,
+    page: envelope.page ?? fallback.page,
+    size: envelope.size ?? fallback.size,
+    total: envelope.total ?? result.length
+  };
+};

package/templates/frontend/src/contracts/metricsSchema.ts

@@ -0,0 +1,84 @@
+import openApi from './openapi.json';
+
+/**
+ * Entity metrics from the contract (JUM-793 / JUM-812). Capabilities live on
+ * `GET …/metrics` as `x-metrics-capabilities`; the frontend never invents
+ * groupable or series fields.
+ */
+
+export type MetricsKind = 'count' | 'groupBy' | 'series';
+export type MetricsInterval = 'day' | 'week' | 'month';
+
+export interface MetricsCapabilities {
+  groupable: string[];
+  series: string[];
+}
+
+export interface MetricsBucket {
+  key: string;
+  count: number;
+  /** Display label when `key` is a foreign key (`x-relation`); absent otherwise. */
+  label?: string;
+}
+
+export interface MetricsResult {
+  metric: MetricsKind;
+  field?: string;
+  interval?: MetricsInterval;
+  buckets: MetricsBucket[];
+}
+
+interface RawOperation {
+  operationId?: string;
+  'x-metrics-capabilities'?: Partial<MetricsCapabilities>;
+}
+
+const document = openApi as { paths?: Record<string, Record<string, RawOperation>> };
+
+const pathForOperation = (operationId: string): string | undefined => {
+  for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+    for (const operation of Object.values(pathItem)) {
+      if (operation?.operationId === operationId) return path;
+    }
+  }
+  return undefined;
+};
+
+export const metricsSpecForListOperation = (
+  listOperationId: string
+): { operationId: string; capabilities: MetricsCapabilities } | undefined => {
+  const listPath = pathForOperation(listOperationId);
+  if (!listPath) return undefined;
+  const metricsPath = `${listPath.replace(/\/$/, '')}/metrics`;
+  const get = document.paths?.[metricsPath]?.get;
+  if (!get?.operationId) return undefined;
+  const raw = get['x-metrics-capabilities'];
+  return {
+    operationId: get.operationId,
+    capabilities: {
+      groupable: raw?.groupable ?? [],
+      series: raw?.series ?? []
+    }
+  };
+};
+
+export const asMetricsResult = (response: unknown): MetricsResult => {
+  const raw = (response ?? {}) as Partial<MetricsResult>;
+  const buckets = Array.isArray(raw.buckets) ? raw.buckets : [];
+  const metric: MetricsKind = raw.metric === 'groupBy' || raw.metric === 'series'
+    ? raw.metric
+    : 'count';
+  let interval: MetricsResult['interval'];
+  if (raw.interval === 'week' || raw.interval === 'month' || raw.interval === 'day') {
+    interval = raw.interval;
+  }
+  return {
+    metric,
+    field: typeof raw.field === 'string' ? raw.field : undefined,
+    interval,
+    buckets: buckets.map((bucket) => ({
+      key: String(bucket.key ?? ''),
+      count: Number(bucket.count) || 0
+    }))
+  };
+};