@jumentix/cli-init 0.0.0

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

@@ -0,0 +1,83 @@
+import openApi from './openapi.json';
+
+/**
+ * RBAC for OAS-driven UIs (JUM-772): the role→scope matrix lives in the spec
+ * (`info.x-rbac`, enforced server-side) and each operation declares its scopes
+ * in `security`. The frontend derives everything from the bundled contract —
+ * it never reads backend code (requirement 136).
+ */
+
+interface RbacOperation {
+  operationId?: string;
+  security?: Array<Record<string, string[]>>;
+}
+
+interface RbacSpec {
+  info?: { 'x-rbac'?: { roles?: Record<string, string[]> } };
+  paths?: Record<string, Record<string, RbacOperation>>;
+}
+
+const spec = openApi as RbacSpec;
+
+/** Role names declared in the OAS matrix (e.g. superadmin, admin, user). */
+export const rbacRoleNames = (): string[] => Object.keys(spec.info?.['x-rbac']?.roles ?? {});
+
+/**
+ * Expands roles into effective scopes using the OAS matrix. Entries that are
+ * not matrix roles (legacy scopes carried loose in the roles array) pass
+ * through as scopes themselves.
+ */
+export const effectiveScopes = (roles: string[] = []): string[] => {
+  const matrix = spec.info?.['x-rbac']?.roles ?? {};
+  const granted = new Set<string>();
+  for (const role of roles) {
+    const mapped = matrix[role];
+    if (mapped) {
+      mapped.forEach((scope) => granted.add(scope));
+    } else {
+      granted.add(role);
+    }
+  }
+  return [...granted];
+};
+
+const operationScopesMap = (): Record<string, string[]> => {
+  const map: Record<string, string[]> = {};
+  for (const pathItem of Object.values(spec.paths ?? {})) {
+    Object.values(pathItem)
+      .filter((operation) => Boolean(operation?.operationId))
+      .forEach((operation) => {
+        // Our spec declares a single bearerAuth requirement per operation; the
+        // scope list inside it is ANDed. Multiple alternatives (OR) are folded.
+        const requirements = (operation.security ?? [])
+          .flatMap((requirement) => Object.values(requirement).flat());
+        map[(operation as { operationId?: string }).operationId as string] = requirements;
+      });
+  }
+  return map;
+};
+
+const scopesByOperation = operationScopesMap();
+
+/** Scopes an operation requires per the OAS (empty = public operation). */
+export const requiredScopes = (operationId: string): string[] => (
+  scopesByOperation[operationId] ?? []
+);
+
+/**
+ * True when the roles satisfy every scope the operation requires. Operations
+ * absent from the contract fail closed (unknown surface is not granted).
+ */
+export const can = (roles: string[] | undefined, operationId: string): boolean => {
+  const required = scopesByOperation[operationId];
+  if (!required) return false;
+  if (required.length === 0) return true;
+  const scopes = effectiveScopes(roles ?? []);
+  if (scopes.includes('*')) return true;
+  return required.every((scope) => scopes.includes(scope));
+};
+
+/** True for superadmin roles (matrix `*`). */
+export const hasSuperadmin = (roles: string[] | undefined): boolean => (
+  effectiveScopes(roles ?? []).includes('*')
+);

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

@@ -0,0 +1,68 @@
+import { getSharedApiClient } from '@/contracts/apiClient';
+import {
+  entityPrimaryKey,
+  fieldDescriptors,
+  listOperationForEntity,
+  type FieldDescriptor
+} from '@/contracts/formSchema';
+import { listCapabilities } from '@/contracts/listSchema';
+import { can } from '@/contracts/rbac';
+import { isCanaOpen } from '@/data/db';
+import { listLocal } from '@/data/localRepository';
+import { useAuthStore } from '@/stores/auth';
+import { useProfileStore } from '@/stores/profile';
+
+type Rows = Array<Record<string, unknown>>;
+type Relation = NonNullable<FieldDescriptor['relation']>;
+
+/**
+ * Display labels for an `x-relation` foreign key, keyed by the stored value.
+ *
+ * Candidates come from the target entity's `<Entity>ArrayOf` operation (or the
+ * local Cana store offline), never from a hardcoded operation id. Anything the
+ * caller cannot read — no list operation, RBAC refusal, network error — yields
+ * an empty map, so callers fall back to the raw value instead of failing.
+ */
+export const loadRelationLabels = async (relation: Relation): Promise<Record<string, string>> => {
+  const operationId = listOperationForEntity(relation.entity);
+  if (!operationId) return {};
+  try {
+    const capabilities = listCapabilities(operationId);
+    let list: Rows;
+    if (isCanaOpen()) {
+      const size = capabilities?.maxSize ?? 100;
+      list = (await listLocal(relation.entity, { page: 1, size })).result;
+    } else if (!can(useProfileStore().record?.roles, operationId)) {
+      list = [];
+    } else {
+      const response = await getSharedApiClient().request<{ result?: Rows } | Rows>({
+        operationId,
+        query: capabilities ? { page: 1, size: capabilities.maxSize } : undefined,
+        headers: { Authorization: useAuthStore().token }
+      });
+      list = Array.isArray(response) ? response : (response.result ?? []);
+    }
+    const labelField = relation.display ?? 'name';
+    const match = relation.match || entityPrimaryKey(relation.entity);
+    return Object.fromEntries(
+      list.map((row) => [String(row[match] ?? row.id), String(row[labelField] ?? row[match] ?? '')])
+    );
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * The `x-relation` of `field` on schema `entity`, when it declares one.
+ *
+ * `undefined` for a schema name the bundled OAS does not declare — callers
+ * (dashboard metrics) pass caller-supplied schema names that are not always
+ * real entities, and `fieldDescriptors` throws on those.
+ */
+export const relationFor = (entity: string, field: string): Relation | undefined => {
+  try {
+    return fieldDescriptors(entity).find((descriptor) => descriptor.name === field)?.relation;
+  } catch {
+    return undefined;
+  }
+};

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

@@ -0,0 +1,59 @@
+import type { Router } from 'vue-router';
+
+import { getSharedApiClient } from '@/contracts/apiClient';
+import { appOperations } from '@/contracts/appOperations';
+import { useAuthStore } from '@/stores/auth';
+import { useProfileStore } from '@/stores/profile';
+
+/**
+ * Session guard (session expiry auto-redirect): the SDK is the only UI↔server
+ * channel, so a 401 on any non-auth operation means the session is dead —
+ * expire locally and land on /login from ANY page, not just /profile.
+ * Auth operations (login/register) are excluded: a 401 there is a wrong
+ * password, not an expired session.
+ */
+
+// Read at event time: the ids are configurable (JUM-780) and a generated app
+// may install them after this module loads.
+const isAuthOperation = (operationId: string): boolean => {
+  const { login, register } = appOperations().auth;
+  return operationId === login || operationId === register;
+};
+
+/** 401 handler wired to the SDK event stream. Returns true when it expired. */
+export const handleSdkEvent = (
+  event: { type: string; status?: number; operationId: string },
+  expire: () => void,
+  redirect: () => void
+): boolean => {
+  if (event.type !== 'request:error' || event.status !== 401) return false;
+  if (isAuthOperation(event.operationId)) return false;
+  expire();
+  redirect();
+  return true;
+};
+
+/** True when the stored session exists but its JWT exp already passed. */
+export const expireIfStaleSession = (auth: ReturnType<typeof useAuthStore>): boolean => {
+  if (auth.isAuthenticated() && auth.isSessionExpired()) {
+    auth.expire();
+    return true;
+  }
+  return false;
+};
+
+/** Installs the global 401→/login reaction on the shared SDK client. */
+export const installSessionGuard = (router: Router): void => {
+  const client = getSharedApiClient();
+  client.subscribe((event) => {
+    const auth = useAuthStore();
+    const profile = useProfileStore();
+    // Reset the profile too: roles cached from the dead session would otherwise
+    // survive into the next login in the same tab (JUM-776 e2e finding).
+    handleSdkEvent(event, () => { auth.expire(); profile.reset(); }, () => {
+      if (router.currentRoute.value.meta.public !== true) {
+        router.push('/login');
+      }
+    });
+  });
+};

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

@@ -0,0 +1,14 @@
+/**
+ * Browser-side shim for @jumentix/shared-contracts.
+ *
+ * The real module reads the OpenAPI YAML from disk (node:fs) — it cannot be
+ * bundled for the browser. The frontend always injects the bundled OAS into
+ * the SDK (requirement 136: the contract is consumed as data), so this shim
+ * is only ever a static placeholder: it fails loudly if anything calls it.
+ */
+export const loadCanonicalSpec = (_input: unknown): never => {
+  throw new Error(
+    'loadCanonicalSpec is unavailable in the browser — inject the bundled spec '
+      + 'from src/contracts/openapi.json instead (requirement 136).'
+  );
+};

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

@@ -0,0 +1,25 @@
+import { computed } from 'vue';
+
+import { can } from '@/contracts/rbac';
+import { useProfileStore } from '@/stores/profile';
+
+/** RBAC for OAS-driven UI (JUM-772): roles of the signed-in user + can(). */
+export const usePermissions = () => {
+  const profile = useProfileStore();
+  const roles = computed<string[]>(() => profile.record?.roles ?? []);
+
+  /** Idempotent: roles come from the profile record; concurrent calls share one flight. */
+  const ensure = async (): Promise<void> => {
+    if (!profile.record) {
+      try {
+        await profile.load();
+      } catch {
+        // roles stay empty → can() fails closed
+      }
+    }
+  };
+
+  const canOp = (operationId: string) => computed(() => can(roles.value, operationId));
+
+  return { roles, ensure, canOp };
+};

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

@@ -0,0 +1,195 @@
+import openApi from './openapi.json';
+import { t } from '@/i18n';
+
+/**
+ * Document/phone masks and validations driven by the `x-validation` blocks
+ * declared in the OAS (JUM-765) — the contract is the single source of these
+ * rules; this module only executes them (requirement 136).
+ */
+
+interface ValidationRule {
+  when: Record<string, string>;
+  pattern?: string;
+  mask?: string;
+  checksum?: string;
+  example?: string;
+}
+
+interface RuleCarrier {
+  components?: {
+    schemas?: Record<string, {
+      properties?: Record<string, { 'x-validation'?: { rules?: ValidationRule[] } }>;
+    }>;
+  };
+}
+
+const rulesOf = (schema: string, property: string): ValidationRule[] => (
+  (openApi as RuleCarrier).components?.schemas?.[schema]?.properties?.[property]?.['x-validation']?.rules ?? []
+);
+
+const documentRules = (): ValidationRule[] => rulesOf('Document', 'data');
+
+const phoneRules = (): ValidationRule[] => rulesOf('Phone', 'number');
+
+export const documentRuleFor = (type: string, countryIssue: string): ValidationRule | undefined => (
+  documentRules().find((rule) => (
+    (!rule.when.type || rule.when.type === type)
+    && (!rule.when.countryIssue || rule.when.countryIssue === countryIssue)
+  ))
+);
+
+export const phoneRuleFor = (countryCode: string): ValidationRule | undefined => (
+  phoneRules().find((rule) => rule.when.countryCode === countryCode)
+);
+
+const digitsOnly = (value: string): string => value.replace(/\D/g, '');
+
+const applyMask = (digits: string, mask: string): string => {
+  let result = '';
+  let digitIndex = 0;
+  for (const char of mask) {
+    if (digitIndex >= digits.length) break;
+    if (char === '0') {
+      result += digits[digitIndex];
+      digitIndex += 1;
+    } else {
+      result += char;
+    }
+  }
+  return result;
+};
+
+/** Progressive CPF mask: digits are grouped 000.000.000-00 as the user types. */
+export const maskCpf = (raw: string): string => (
+  applyMask(digitsOnly(raw).slice(0, 11), '000.000.000-00')
+);
+
+/** Progressive SSN mask: 000-00-0000. */
+export const maskSsn = (raw: string): string => (
+  applyMask(digitsOnly(raw).slice(0, 9), '000-00-0000')
+);
+
+/** Progressive phone mask by country rule declared in the OAS. */
+export const maskPhone = (countryCode: string, raw: string): string => {
+  const rule = phoneRuleFor(countryCode);
+  const digits = digitsOnly(raw).slice(0, 9);
+  if (!rule?.mask) {
+    return digits;
+  }
+  return applyMask(digits, rule.mask);
+};
+
+/**
+ * Extracts the declared char class from anchored class patterns
+ * (`^[A-Za-z0-9]{5,20}$` → `A-Za-z0-9`). Returns undefined for any other
+ * shape — digit-pattern rules (CPF/SSN/phone) are handled by masks instead.
+ */
+export const patternAlphabet = (pattern: string | undefined): string | undefined => (
+  pattern?.match(/^\^\[([^\]]+)\]\{\d+(?:,\d*)?\}\$$/)?.[1]
+);
+
+/**
+ * Extracts the upper bound of the quantifier in an anchored class pattern
+ * (`{5,20}` → 20, `{11}` → 11, `{5,}` → undefined = unbounded).
+ */
+export const patternCap = (pattern: string | undefined): number | undefined => {
+  const quantifier = pattern?.match(/^\^\[[^\]]+\]\{(\d+)(,(\d*))?\}\$$/);
+  if (!quantifier) return undefined;
+  if (quantifier[2] !== undefined) {
+    // `{m,}` is unbounded; `{m,n}` caps at n.
+    return quantifier[3] ? Number(quantifier[3]) : undefined;
+  }
+  return Number(quantifier[1]);
+};
+
+/**
+ * Input filter for a document's data (JUM-769): CPF/SSN keep their masks;
+ * pattern-only rules (passport, RG) strip characters outside the declared
+ * alphabet and hard-cap at the pattern's upper bound, so over-typing is
+ * blocked at the input instead of failing at save time. Types with no
+ * declared rule stay free-form per OAS.
+ */
+export const filterDocumentData = (type: string, countryIssue: string, raw: string): string => {
+  if (type === 'CPF') return maskCpf(raw);
+  if (type === 'SSN') return maskSsn(raw);
+  const rule = documentRuleFor(type, countryIssue);
+  const alphabet = patternAlphabet(rule?.pattern);
+  if (!alphabet) return raw;
+  const filtered = raw.replace(new RegExp(`[^${alphabet}]`, 'g'), '');
+  const cap = patternCap(rule?.pattern);
+  return cap === undefined ? filtered : filtered.slice(0, cap);
+};
+
+/** Input cap for a document's data: OAS mask length, or the pattern's upper bound. */
+export const documentInputCap = (type: string, countryIssue: string): number | undefined => {
+  const rule = documentRuleFor(type, countryIssue);
+  if (!rule) return undefined;
+  return rule.mask ? rule.mask.length : patternCap(rule.pattern);
+};
+
+/** Input cap for a phone number from the OAS mask of the country rule. */
+export const phoneMaskCap = (countryCode: string): number | undefined => {
+  const rule = phoneRuleFor(countryCode);
+  return rule?.mask ? rule.mask.length : undefined;
+};
+
+/** Modulo-11 checksum for the two CPF verification digits. */
+export const isValidCpf = (value: string): boolean => {
+  const digits = digitsOnly(value);
+  if (digits.length !== 11 || /^(\d)\1{10}$/.test(digits)) {
+    return false;
+  }
+  const numbers = digits.split('').map(Number);
+  const checksum = (count: number): number => {
+    const sum = numbers.slice(0, count - 1).reduce((acc, n, i) => acc + n * (count - i), 0);
+    const digit = (sum * 10) % 11;
+    return digit === 10 ? 0 : digit;
+  };
+  return checksum(10) === numbers[9] && checksum(11) === numbers[10];
+};
+
+const matches = (pattern: string | undefined, value: string): boolean => (
+  pattern ? new RegExp(pattern).test(value) : true
+);
+
+/**
+ * Full document validation: OAS pattern for the type+country, plus the CPF
+ * checksum when the rule declares one.
+ */
+export const validateDocumentData = (
+  type: string,
+  countryIssue: string,
+  value: string
+): string | null => {
+  if (!value.trim()) {
+    return t('validation.documentRequired');
+  }
+  const rule = documentRuleFor(type, countryIssue);
+  if (!rule) {
+    return null; // no declared rule for this type+country — free-form per OAS
+  }
+  if (!matches(rule.pattern, value)) {
+    const example = rule.example ? t('validation.documentExample', { example: rule.example }) : '';
+    return `${t('validation.documentFormat', { type })}${example}.`;
+  }
+  if (rule.checksum === 'cpf-mod11' && !isValidCpf(value)) {
+    return t('validation.cpfChecksum');
+  }
+  return null;
+};
+
+/** Phone validation against the OAS rule for the country code. */
+export const validatePhone = (
+  countryCode: string,
+  localCode: string,
+  value: string
+): string | null => {
+  if (!value.trim()) {
+    return t('validation.phoneRequired');
+  }
+  const rule = phoneRuleFor(countryCode);
+  if (rule?.pattern && !matches(rule.pattern, value)) {
+    return t('validation.phoneFormat', { country: countryCode, example: rule.example ?? '0000-0000' });
+  }
+  return null;
+};

package/templates/frontend/src/data/canaSchema.ts

@@ -0,0 +1,146 @@
+import type { CanaSchema, CanaStoreSchema } from '@jumentix/cana';
+
+import openApi from '@/contracts/openapi.json';
+import {
+  entityPrimaryKey, fieldDescriptors, getOperationForEntity, listOperationForEntity
+} from '@/contracts/formSchema';
+import { listCapabilities } from '@/contracts/listSchema';
+
+export const DATABASE_NAME = 'jumentix-frontend';
+export const META_STORE = 'meta';
+export const OUTBOX_STORE = 'outbox';
+export const SCHEMA_META_ID = 'schema';
+export const SESSION_META_ID = 'session';
+
+export interface EntityTableSpec {
+  schemaName: string;
+  storeName: string;
+  keyPath: string;
+  indexes: string[];
+  listOperationId: string;
+  getOperationId?: string;
+}
+
+interface OpenApiPaths {
+  paths?: Record<string, Record<string, { operationId?: string }>>;
+  info?: { title?: string };
+}
+
+const document = openApi as OpenApiPaths;
+
+const storeNameFromListPath = (operationId: string, schemaName: string): string => {
+  for (const [path, methods] of Object.entries(document.paths ?? {})) {
+    for (const operation of Object.values(methods)) {
+      if (operation?.operationId === operationId) {
+        const segment = path.split('/').filter(Boolean).at(-1);
+        if (segment) return segment;
+      }
+    }
+  }
+  return `${schemaName[0]?.toLowerCase() ?? ''}${schemaName.slice(1)}s`;
+};
+
+const relationFields = (schemaName: string): string[] => (
+  fieldDescriptors(schemaName)
+    .filter((descriptor) => descriptor.relation)
+    .map((descriptor) => descriptor.relation!.field)
+);
+
+export const deriveEntityTables = (): EntityTableSpec[] => {
+  const schemas = (openApi as {
+    components?: { schemas?: Record<string, unknown> };
+  }).components?.schemas ?? {};
+  const tables: EntityTableSpec[] = [];
+  for (const schemaName of Object.keys(schemas)) {
+    const listOperationId = listOperationForEntity(schemaName);
+    if (listOperationId) {
+      const keyPath = entityPrimaryKey(schemaName);
+      const capabilities = listCapabilities(listOperationId);
+      // IndexedDB rejects array values on a non-multiEntry index (DataError).
+      // OAS `roles` / `members` / `emails` are arrays even when x-list-capabilities
+      // lists them as filterable enums — never promote those fields to indexes.
+      const arrayFields = new Set(
+        fieldDescriptors(schemaName)
+          .filter((descriptor) => descriptor.type === 'array')
+          .map((descriptor) => descriptor.name)
+      );
+      const indexSet = new Set<string>([
+        ...(capabilities?.sortable ?? []),
+        ...Object.keys(capabilities?.filterable ?? {}),
+        'updatedAt',
+        'deletedAt',
+        ...relationFields(schemaName)
+      ]);
+      indexSet.delete(keyPath);
+      for (const field of arrayFields) indexSet.delete(field);
+      tables.push({
+        schemaName,
+        storeName: storeNameFromListPath(listOperationId, schemaName),
+        keyPath,
+        indexes: [...indexSet],
+        listOperationId,
+        getOperationId: getOperationForEntity(schemaName)
+      });
+    }
+  }
+  return tables.sort((left, right) => left.storeName.localeCompare(right.storeName));
+};
+
+export const entityTable = (schemaName: string): EntityTableSpec => {
+  const found = deriveEntityTables().find((table) => table.schemaName === schemaName);
+  if (!found) {
+    throw new Error(`No Cana table for OAS entity ${schemaName}`);
+  }
+  return found;
+};
+
+export const entityTableByStore = (storeName: string): EntityTableSpec | undefined => (
+  deriveEntityTables().find((table) => table.storeName === storeName)
+);
+
+export const schemaFingerprint = (stores: readonly CanaStoreSchema[]): string => (
+  JSON.stringify(stores)
+);
+
+/** Stable positive integer in `[1, 2^31-2]` from the derived store set. */
+export const schemaVersionFromStores = (stores: readonly CanaStoreSchema[]): number => {
+  const fingerprint = schemaFingerprint(stores);
+  let hash = 2166136261;
+  for (let index = 0; index < fingerprint.length; index += 1) {
+    // FNV-1a — bitwise on purpose.
+    // eslint-disable-next-line no-bitwise
+    hash ^= fingerprint.codePointAt(index) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+  // eslint-disable-next-line no-bitwise
+  return ((hash >>> 0) % 2147483646) + 1;
+};
+
+const toStore = (table: EntityTableSpec): CanaStoreSchema => ({
+  name: table.storeName,
+  keyPath: table.keyPath,
+  indexes: table.indexes.map((name) => ({ name, keyPath: name }))
+});
+
+export const buildCanaStores = (): CanaStoreSchema[] => {
+  const entities = deriveEntityTables().map(toStore);
+  return [
+    ...entities,
+    { name: META_STORE, keyPath: 'id' },
+    {
+      name: OUTBOX_STORE,
+      keyPath: 'opId',
+      indexes: [
+        { name: 'createdAt', keyPath: 'createdAt' },
+        { name: 'entity', keyPath: 'entity' }
+      ]
+    }
+  ];
+};
+
+export const buildCanaSchema = (): CanaSchema => {
+  const stores = buildCanaStores();
+  return { version: schemaVersionFromStores(stores), stores };
+};
+
+export const appManifestName = (): string => document.info?.title ?? 'Jumentix Frontend';