@shokirovr16/frontend-library 0.1.2

package/src/auth/tenancy/TenantResolver.js

@@ -0,0 +1,39 @@
+/**
+ * @typedef {Object} Tenant
+ * @property {string} tenantId
+ * @property {string} [tenantSlug]
+ */
+
+/**
+ * @typedef {Object} TenantResolver
+ * @property {()=>Promise<Tenant>|Tenant} resolve
+ */
+
+/**
+ * Default resolver (SPA): try `?tenant=...`, then first path segment, then subdomain.
+ * This is a heuristic; production apps usually provide a dedicated runtime-config endpoint instead.
+ */
+export function createDefaultTenantResolver({ param = 'tenant', pathIndex = 0 } = {}) {
+  return {
+    resolve() {
+      if (typeof window === 'undefined') return { tenantId: 'default' };
+      const url = new URL(window.location.href);
+      const fromParam = url.searchParams.get(param);
+      if (fromParam) return { tenantId: fromParam, tenantSlug: fromParam };
+
+      const parts = window.location.pathname.split('/').filter(Boolean);
+      const fromPath = parts[pathIndex];
+      if (fromPath) return { tenantId: fromPath, tenantSlug: fromPath };
+
+      const host = window.location.hostname;
+      const hostParts = host.split('.').filter(Boolean);
+      if (hostParts.length > 2) {
+        const sub = hostParts[0];
+        if (sub && sub !== 'www') return { tenantId: sub, tenantSlug: sub };
+      }
+
+      return { tenantId: 'default' };
+    },
+  };
+}
+

package/src/auth/types.js

@@ -0,0 +1,113 @@
+/**
+ * This file documents the runtime types for the auth module (JS implementation).
+ * It exists to make the public API discoverable without requiring TS build tooling.
+ */
+
+/**
+ * @typedef {'spa-direct'|'bff'} AuthMode
+ */
+
+/**
+ * @typedef {'disabled'|'onLoad'|'onDemand'} CheckSsoPolicy
+ */
+
+/**
+ * @typedef {'memory'} TokenStoreType
+ */
+
+/**
+ * @typedef {Object} TokenPolicy
+ * @property {number} [minValiditySec] Default min validity for ensureFreshToken (seconds)
+ * @property {number} [refreshLeewaySec] Leeway applied when computing expiry (seconds)
+ */
+
+/**
+ * @typedef {Object} LogoutPolicy
+ * @property {boolean} [frontChannel] When true, redirects to OIDC end_session_endpoint (recommended for Keycloak)
+ * @property {boolean} [broadcast] When true, broadcasts logout to same-origin tabs
+ */
+
+/**
+ * @typedef {Object} ClaimsPolicy
+ * @property {string[]} [roleClaimPaths] Dot/bracket paths to role arrays (e.g. ['realm_access.roles','resource_access[{clientId}].roles'])
+ * @property {string[]} [permissionClaimPaths] Dot/bracket paths to permission arrays
+ * @property {Record<string,string>} [profileClaimPaths] Map from normalized key -> claim path (e.g. { email: 'email', username: 'preferred_username' })
+ */
+
+/**
+ * @typedef {Object} AuthRuntimeConfig
+ * @property {string} tenantId
+ * @property {string} [tenantSlug]
+ * @property {AuthMode} [mode]
+ * @property {string} issuer OIDC issuer, for Keycloak usually: https://<host>/realms/<realm>
+ * @property {string} clientId
+ * @property {string[]} [scopes]
+ * @property {string} redirectUri
+ * @property {string} [postLogoutRedirectUri]
+ * @property {string} [silentCheckSsoRedirectUri] Required for check-sso via hidden iframe (same-origin is recommended)
+ * @property {CheckSsoPolicy} [checkSsoPolicy]
+ * @property {TokenPolicy} [tokenPolicy]
+ * @property {LogoutPolicy} [logoutPolicy]
+ * @property {ClaimsPolicy} [claimsPolicy]
+ */
+
+/**
+ * @typedef {Object} Tenant
+ * @property {string} tenantId
+ * @property {string} [tenantSlug]
+ */
+
+/**
+ * @typedef {Object} InitializeAuthOptions
+ * @property {AuthRuntimeConfig|(()=>Promise<AuthRuntimeConfig>)} runtimeConfig Runtime config object or async loader
+ * @property {import('./tenancy/TenantResolver.js').TenantResolver} [tenantResolver]
+ * @property {(cfg: AuthRuntimeConfig)=>AuthRuntimeConfig} [validateAndNormalizeConfig]
+ * @property {string} [broadcastChannelName]
+ * @property {(event: any)=>void} [onEvent]
+ */
+
+/**
+ * @typedef {Object} AuthUser
+ * @property {string} [sub]
+ * @property {string} [name]
+ * @property {string} [email]
+ * @property {string} [username]
+ * @property {string[]} roles
+ * @property {string[]} permissions
+ * @property {Record<string, any>} claims
+ */
+
+/**
+ * @typedef {Object} AuthSnapshot
+ * @property {string} status
+ * @property {boolean} isAuthenticated
+ * @property {string|null} tenantId
+ * @property {AuthUser|null} user
+ * @property {string|null} error
+ */
+
+/**
+ * @typedef {Object} AuthEngine
+ * @property {()=>AuthSnapshot} getSnapshot
+ * @property {(listener:(snapshot:AuthSnapshot)=>void)=>()=>void} subscribe
+ * @property {(listener:(event:any)=>void)=>()=>void} subscribeAuthEvents
+ * @property {(params?:{returnTo?:string,prompt?:string})=>Promise<never>} login
+ * @property {(params?:{postLogoutRedirectUri?:string})=>Promise<never|void>} logout
+ * @property {(params?:{url?:string})=>Promise<{returnTo?:string}>} handleCallback
+ * @property {(event:MessageEvent)=>Promise<void>} handleSilentCallbackMessage
+ * @property {(minValiditySec?:number)=>Promise<void>} ensureFreshToken
+ * @property {()=>Promise<void>} refresh
+ * @property {()=>string|null} getAccessToken
+ * @property {()=>string|null} getIdToken
+ * @property {()=>boolean} isAuthenticated
+ * @property {()=>AuthUser|null} getUser
+ * @property {(reason?:string)=>void} clearSession
+ * @property {(tenant:Tenant)=>Promise<void>} setTenant
+ * @property {(tenant:Tenant, opts?:{checkSso?:boolean})=>Promise<void>} switchTenant
+ * @property {(role:string)=>boolean} hasRole
+ * @property {(roles:string[])=>boolean} hasAnyRole
+ * @property {(roles:string[])=>boolean} hasAllRoles
+ * @property {(permission:string)=>boolean} hasPermission
+ * @property {(permission:string)=>boolean} can
+ */
+

package/src/auth/utils/base64url.js

@@ -0,0 +1,15 @@
+export function base64UrlToUint8Array(value) {
+  const base64 = value.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(value.length / 4) * 4, '=');
+  const raw = atob(base64);
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+}
+
+export function uint8ArrayToBase64Url(bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  const base64 = btoa(binary);
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+

package/src/auth/utils/jwt.js

@@ -0,0 +1,26 @@
+import { base64UrlToUint8Array } from './base64url.js';
+
+export function decodeJwt(token) {
+  if (!token) return null;
+  const parts = token.split('.');
+  if (parts.length < 2) return null;
+  try {
+    const json = new TextDecoder().decode(base64UrlToUint8Array(parts[1]));
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+export function getJwtExp(token) {
+  const payload = decodeJwt(token);
+  const exp = payload?.exp;
+  return typeof exp === 'number' ? exp : null;
+}
+
+export function isJwtExpired(token, nowSec = Math.floor(Date.now() / 1000), leewaySec = 0) {
+  const exp = getJwtExp(token);
+  if (!exp) return true;
+  return exp <= nowSec + leewaySec;
+}
+

package/src/auth/utils/random.js

@@ -0,0 +1,13 @@
+export function randomString(length = 32) {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  const bytes = new Uint8Array(length);
+  const cryptoObj = globalThis.crypto;
+  if (!cryptoObj?.getRandomValues) {
+    throw new Error('[cmfrt/auth] crypto.getRandomValues is required (browser secure context).');
+  }
+  cryptoObj.getRandomValues(bytes);
+  let out = '';
+  for (let i = 0; i < bytes.length; i++) out += alphabet[bytes[i] % alphabet.length];
+  return out;
+}
+

package/src/auth/utils/url.js

@@ -0,0 +1,27 @@
+export function toAbsoluteUrl(maybeRelativeUrl) {
+  if (!maybeRelativeUrl) return null;
+  try {
+    return new URL(maybeRelativeUrl, globalThis.location?.origin).toString();
+  } catch {
+    return null;
+  }
+}
+
+export function getCurrentUrl() {
+  if (typeof window === 'undefined') return null;
+  return window.location.href;
+}
+
+export function stripQueryParams(url, keysToStrip) {
+  const u = new URL(url);
+  for (const key of keysToStrip) u.searchParams.delete(key);
+  return u.toString();
+}
+
+export function parseUrlParams(url) {
+  const u = new URL(url);
+  const params = {};
+  for (const [k, v] of u.searchParams.entries()) params[k] = v;
+  return params;
+}
+

package/src/commands/add.js

@@ -0,0 +1,80 @@
+import path from 'path';
+import pc from 'picocolors';
+import { copyFile, ensureDirectory, pathExists } from '../lib/fs.js';
+import { templatePath } from '../lib/paths.js';
+import { readRegistry } from '../lib/registry.js';
+import { loadConfig, writeConfig } from '../lib/config.js';
+import { installDependencies } from '../lib/packageManager.js';
+import { resolveTargetRoot } from '../lib/targets.js';
+import { ensureStylesInstalled } from '../lib/styles.js';
+
+async function resolveTargetPath(targetPath) {
+  if (!(await pathExists(targetPath))) {
+    return targetPath;
+  }
+
+  const { dir, name, ext } = path.parse(targetPath);
+  let counter = 0;
+
+  while (true) {
+    const suffix = counter === 0 ? '.new' : `.new${counter}`;
+    const candidate = path.join(dir, `${name}${suffix}${ext}`);
+    if (!(await pathExists(candidate))) {
+      return candidate;
+    }
+    counter += 1;
+  }
+}
+
+const { green, yellow, red } = pc;
+
+export default async function addCommand(componentName) {
+  const config = await loadConfig();
+  const registry = await readRegistry();
+  const component = registry[componentName];
+
+  if (!component) {
+    const message = `No component named "${componentName}" is registered.`;
+    console.error(red(message));
+    throw new Error(message);
+  }
+
+  const componentsRoot = resolveTargetRoot(component, config);
+
+  await ensureDirectory(componentsRoot);
+
+  const installedFiles = [];
+
+  for (const file of component.files ?? []) {
+    const source = templatePath(file.source);
+    const destination = path.resolve(componentsRoot, file.target);
+    await ensureDirectory(path.dirname(destination));
+
+    const finalTarget = await resolveTargetPath(destination);
+    if (finalTarget !== destination) {
+      console.log(yellow(`Target already exists; writing to ${path.basename(finalTarget)} instead.`));
+    }
+
+    await copyFile(source, finalTarget, { overwrite: false });
+    installedFiles.push(path.relative(componentsRoot, finalTarget));
+  }
+
+  await installDependencies(component.dependencies ?? []);
+
+  let updated = {
+    ...config,
+    installed: {
+      ...config.installed,
+      [componentName]: {
+        version: component.version ?? '0.0.0',
+        files: installedFiles,
+        installedAt: new Date().toISOString(),
+      },
+    },
+  };
+  const stylesResult = await ensureStylesInstalled(registry, updated);
+  updated = stylesResult.config;
+  await writeConfig(updated);
+
+  console.log(green(`${componentName} is ready under src/components/ui.`));
+}

package/src/commands/init.js

@@ -0,0 +1,113 @@
+import path from 'path';
+import pc from 'picocolors';
+import prompts from 'prompts';
+
+import { configExists, createDefaultConfig, writeConfig } from '../lib/config.js';
+import { copyFile, ensureDirectory, pathExists, readJson } from '../lib/fs.js';
+import { componentsDir, libDir, projectRoot, templatePath } from '../lib/paths.js';
+import { applyThemeMode, getAvailableModes, resolveMode } from '../lib/theme.js';
+import { readRegistry } from '../lib/registry.js';
+import { ensureStylesInstalled } from '../lib/styles.js';
+
+const TAILWIND_PACKAGE = 'tailwindcss';
+const { green, red, yellow } = pc;
+
+const TAILWIND_CONFIG_CANDIDATES = [
+  'tailwind.config.js',
+  'tailwind.config.cjs',
+  'tailwind.config.mjs',
+];
+
+const detectTailwindConfig = async () => {
+  for (const filename of TAILWIND_CONFIG_CANDIDATES) {
+    const configPath = path.resolve(process.cwd(), filename);
+    if (await pathExists(configPath)) {
+      return configPath;
+    }
+  }
+  return null;
+};
+
+const printManualTailwindInstructions = () => {
+  console.log(yellow('Tailwind config not found. Please add tailwind.config.js/.cjs/.mjs manually.'));
+};
+
+export default async function initCommand() {
+  const packageJsonPath = path.resolve(process.cwd(), 'package.json');
+  if (!(await pathExists(packageJsonPath))) {
+    throw new Error('package.json not found in the current directory.');
+  }
+
+  const packageJson = await readJson(packageJsonPath);
+  const hasTailwind = Boolean(
+    packageJson.dependencies?.[TAILWIND_PACKAGE] || packageJson.devDependencies?.[TAILWIND_PACKAGE]
+  );
+
+  if (!hasTailwind) {
+    const message = 'Tailwind CSS is missing from package.json. Install tailwindcss before running cmfrt init.';
+    console.error(red(message));
+    throw new Error(message);
+  }
+
+  await ensureDirectory(componentsDir());
+  await ensureDirectory(libDir());
+
+  const utilsTarget = path.resolve(libDir(), 'utils.js');
+  if (await pathExists(utilsTarget)) {
+    console.log(yellow('src/lib/utils.js already exists, skipping template copy.'));
+  } else {
+    await copyFile(templatePath('lib', 'utils.js'), utilsTarget);
+  }
+
+  const docTarget = path.resolve(projectRoot(), 'cmfrt-doc.md');
+  if (await pathExists(docTarget)) {
+    console.log(yellow('cmfrt-doc.md already exists, skipping doc copy.'));
+  } else {
+    await copyFile(templatePath('docs', 'cmfrt-doc.md'), docTarget);
+  }
+
+  if (await configExists()) {
+    console.log(yellow('cmfrt.json already exists, reusing configuration.'));
+  } else {
+    await writeConfig(createDefaultConfig());
+    console.log(green('Created cmfrt.json and default configuration.'));
+  }
+
+  try {
+    const registry = await readRegistry();
+    const currentConfig = await readJson(path.resolve(projectRoot(), 'cmfrt.json'));
+    const result = await ensureStylesInstalled(registry, currentConfig);
+    if (result.updated) {
+      await writeConfig(result.config);
+    }
+  } catch (error) {
+    console.log(yellow('Failed to install styles during init.'));
+  }
+
+  const modes = await getAvailableModes({ stylesPath: 'src/styles' });
+  if (modes.length > 0) {
+    const response = await prompts({
+      type: 'select',
+      name: 'mode',
+      message: 'Select a theme mode',
+      choices: modes.map((mode) => ({ title: mode.name, value: mode.safe })),
+    });
+
+    const selected = resolveMode(modes, response.mode);
+    if (selected) {
+      const result = await applyThemeMode(selected.safe);
+      if (result.updated) {
+        const current = await readJson(path.resolve(projectRoot(), 'cmfrt.json'));
+        await writeConfig({ ...current, themeMode: selected.name });
+        console.log(green(`Theme mode set: ${selected.name}`));
+      }
+    }
+  }
+
+  const tailwindConfigPath = await detectTailwindConfig();
+  if (!tailwindConfigPath) {
+    printManualTailwindInstructions();
+  }
+
+  console.log(green('Comfort CLI scaffold created under src/components/ui.'));
+}

package/src/commands/list.js

@@ -0,0 +1,92 @@
+import pc from 'picocolors';
+import { readRegistry } from '../lib/registry.js';
+
+const { cyan, green, dim, red } = pc;
+
+function normalizeCategory(category) {
+  const raw = String(category ?? '').trim();
+  return raw.length > 0 ? raw : 'uncategorized';
+}
+
+function normalizeDescription(description) {
+  return String(description ?? '').trim();
+}
+
+function matchesSearch(text, query) {
+  if (!query) return true;
+  return text.toLowerCase().includes(query.toLowerCase());
+}
+
+export default async function listCommand(options = {}) {
+  try {
+    const registry = await readRegistry();
+    const entries = Object.entries(registry ?? {});
+
+    let items = entries.map(([name, entry]) => {
+      const category = normalizeCategory(entry?.category);
+      const description = normalizeDescription(entry?.description);
+
+      return {
+        name,
+        version: entry?.version ?? '0.0.0',
+        category,
+        description,
+        filesCount: Array.isArray(entry?.files) ? entry.files.length : 0,
+        dependenciesCount: Array.isArray(entry?.dependencies) ? entry.dependencies.length : 0,
+      };
+    });
+
+    if (options.category) {
+      const categoryFilter = String(options.category).toLowerCase();
+      items = items.filter((item) => item.category.toLowerCase() === categoryFilter);
+    }
+
+    if (options.search) {
+      const search = String(options.search).toLowerCase();
+      items = items.filter(
+        (item) =>
+          matchesSearch(item.name, search) || matchesSearch(item.description, search)
+      );
+    }
+
+    items.sort((a, b) => {
+      const categoryCompare = a.category.localeCompare(b.category);
+      if (categoryCompare !== 0) return categoryCompare;
+      return a.name.localeCompare(b.name);
+    });
+
+    const categories = Array.from(new Set(items.map((item) => item.category)));
+
+    if (options.json) {
+      const payload = {
+        count: items.length,
+        categories,
+        items: items.map(({ name, version, category, description }) => ({
+          name,
+          version,
+          category,
+          description,
+        })),
+      };
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    let currentCategory = null;
+    for (const item of items) {
+      if (item.category !== currentCategory) {
+        currentCategory = item.category;
+        console.log(cyan(currentCategory));
+      }
+
+      const versionLabel = dim(`(${item.version})`);
+      const description = item.description ? `  ${item.description}` : '';
+      console.log(`  - ${green(item.name)} ${versionLabel}${description}`);
+    }
+
+    console.log(`Summary: ${items.length} components across ${categories.length} categories`);
+  } catch (error) {
+    console.error(red(error?.message ?? 'Failed to load registry.'));
+    process.exitCode = 1;
+  }
+}

package/src/commands/remove.js

@@ -0,0 +1,150 @@
+import path from 'path';
+import pc from 'picocolors';
+import prompts from 'prompts';
+import { execa } from 'execa';
+import { configExists, loadConfig, writeConfig } from '../lib/config.js';
+import { readRegistry } from '../lib/registry.js';
+import { pathExists, removePath } from '../lib/fs.js';
+import { componentsDir, projectRoot } from '../lib/paths.js';
+import { resolveTargetRoot } from '../lib/targets.js';
+
+const { green, yellow, red, cyan } = pc;
+
+async function confirmRemoval(name) {
+  const response = await prompts({
+    type: 'confirm',
+    name: 'confirm',
+    message: `Are you sure you want to remove ${name}?`,
+    initial: false,
+  });
+
+  return Boolean(response.confirm);
+}
+
+function resolveComponentsRoot(config) {
+  return config.componentsPath
+    ? path.resolve(projectRoot(), config.componentsPath)
+    : componentsDir();
+}
+
+function shouldSkipUtils(targetPath, config) {
+  if (!config.utilsPath) return false;
+  const utilsPath = path.resolve(projectRoot(), config.utilsPath);
+  return path.resolve(targetPath) === utilsPath;
+}
+
+export default async function removeCommand(componentName, options = {}) {
+  if (!(await configExists())) {
+    console.error(red('cmfrt.json is missing. Run cmfrt init first.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!componentName) {
+    console.error(red('Please provide a component name.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const config = await loadConfig();
+  const installedEntry = config.installed?.[componentName];
+
+  if (!installedEntry) {
+    console.log(yellow(`Component "${componentName}" is not installed.`));
+    return;
+  }
+
+  if (!options.yes) {
+    const confirmed = await confirmRemoval(componentName);
+    if (!confirmed) {
+      console.log(yellow('Aborted.'));
+      return;
+    }
+  }
+
+  let registry = null;
+  try {
+    registry = await readRegistry();
+  } catch {
+    registry = null;
+  }
+
+  const registryEntry = registry?.[componentName];
+  const componentsRoot = registryEntry
+    ? resolveTargetRoot(registryEntry, config)
+    : resolveComponentsRoot(config);
+  console.log(`Removing: ${componentName}`);
+
+  for (const file of installedEntry.files ?? []) {
+    const destination = path.resolve(componentsRoot, file);
+
+    if (shouldSkipUtils(destination, config)) {
+      continue;
+    }
+
+    if (await pathExists(destination)) {
+      await removePath(destination);
+      const relativePath = path.relative(projectRoot(), destination) || destination;
+      console.log(`Deleted: ${relativePath}`);
+    }
+  }
+
+  const updatedInstalled = { ...(config.installed ?? {}) };
+  delete updatedInstalled[componentName];
+
+  const updatedConfig = {
+    ...config,
+    installed: updatedInstalled,
+  };
+
+  await writeConfig(updatedConfig);
+
+  if (options.prune) {
+    if (!registry) {
+      console.error(red('Failed to load registry for pruning dependencies.'));
+      process.exitCode = 1;
+      console.log(green('Component removed successfully.'));
+      return;
+    }
+
+    const entry = registry?.[componentName];
+    if (!entry) {
+      console.log(yellow(`Registry entry for "${componentName}" not found. Skipping prune.`));
+    } else {
+      const dependencies = Array.isArray(entry.dependencies) ? entry.dependencies : [];
+      const otherInstalled = Object.keys(updatedInstalled);
+
+      for (const dependency of dependencies) {
+        let usedElsewhere = false;
+
+        for (const otherName of otherInstalled) {
+          const otherEntry = registry?.[otherName];
+          if (!otherEntry) {
+            usedElsewhere = true;
+            break;
+          }
+          const otherDeps = Array.isArray(otherEntry.dependencies) ? otherEntry.dependencies : [];
+          if (otherDeps.includes(dependency)) {
+            usedElsewhere = true;
+            break;
+          }
+        }
+
+        if (usedElsewhere) {
+          continue;
+        }
+
+        try {
+          console.log(cyan(`Uninstalling: ${dependency}`));
+          await execa('npm', ['uninstall', dependency]);
+          console.log(`Uninstalled: ${dependency}`);
+        } catch (error) {
+          console.error(red(`Failed to uninstall ${dependency}.`));
+          process.exitCode = 1;
+        }
+      }
+    }
+  }
+
+  console.log(green('Component removed successfully.'));
+}