vk-typescript-cli 1.0.0

package/src/utils/ansi-colors.js

@@ -0,0 +1,38 @@
+const ansi = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  gray: '\x1b[90m',
+  white: '\x1b[97m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m'
+};
+
+function wrap(text, ...codes) {
+  return `${codes.join('')}${text}${ansi.reset}`;
+}
+
+function hexToRgb(hex) {
+  const normalized = hex.replace('#', '');
+  const value = normalized.length === 3
+    ? normalized.split('').map((char) => char + char).join('')
+    : normalized;
+
+  const parsed = Number.parseInt(value, 16);
+  return {
+    r: (parsed >> 16) & 255,
+    g: (parsed >> 8) & 255,
+    b: parsed & 255
+  };
+}
+
+function rgb(text, hex, { bold = false } = {}) {
+  const { r, g, b } = hexToRgb(hex);
+  const rgbCode = `\x1b[38;2;${r};${g};${b}m`;
+  return wrap(text, bold ? ansi.bold : '', rgbCode);
+}
+
+export { ansi, wrap, hexToRgb, rgb };

package/src/utils/banner.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ansi, rgb, wrap } from './ansi-colors.js';
+
+function gray(text) {
+  return wrap(text, ansi.gray);
+}
+
+function cyan(text) {
+  return wrap(text, ansi.cyan);
+}
+
+function bold(text) {
+  return wrap(text, ansi.bold);
+}
+
+function boldWhite(text) {
+  return wrap(text, ansi.bold, ansi.white);
+}
+
+const brand = (text) => rgb(text, '#00BCEB');
+const brandBold = (text) => rgb(text, '#00BCEB', { bold: true });
+const brandDark = (text) => rgb(text, '#1B6E7A');
+const accent = (text) => rgb(text, '#7C3AED');
+
+function getTerminalWidth() {
+  const width = process.stdout.columns || 75;
+  const MIN_WIDTH = 75;
+  const MAX_WIDTH = 60;
+  return Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, width));
+}
+
+// Then use it dynamically:
+const BOX_WIDTH = getTerminalWidth();
+const INNER_WIDTH = BOX_WIDTH - 2;
+
+function stripAnsi(text) {
+  const ESC = String.fromCharCode(27);
+  return String(text).replace(new RegExp(`${ESC}\\[[0-9;]*m`, 'g'), '');
+}
+
+function boxLine(content, color = brandDark) {
+  const plainLen = stripAnsi(content).length;
+  const padding = Math.max(0, INNER_WIDTH - plainLen);
+
+  return color('║') + content + ' '.repeat(padding) + color('║');
+}
+
+function boxTop(color = brandDark) {
+  return color('╔' + '═'.repeat(INNER_WIDTH) + '╗');
+}
+
+function boxBottom(color = brandDark) {
+  return color('╚' + '═'.repeat(INNER_WIDTH) + '╝');
+}
+
+function boxCenterLine(content, color = brandDark) {
+  const plainLen = stripAnsi(content).length;
+  const totalPadding = Math.max(0, INNER_WIDTH - plainLen);
+  const leftPadding = Math.floor(totalPadding / 2);
+  const rightPadding = totalPadding - leftPadding;
+
+  return (
+    color('║') +
+    ' '.repeat(leftPadding) +
+    content +
+    ' '.repeat(rightPadding) +
+    color('║')
+  );
+}
+
+export function printBanner(version = '1.0.1') {
+  const width = 64;
+  const leftText = bold('Syncfusion CLI');
+  const rightText = gray(`v${version}`);
+
+  const plainLeftLength = 'Syncfusion CLI'.length;
+  const plainRightLength = `v${version}`.length;
+  const gapSize = Math.max(1, width - plainLeftLength - plainRightLength);
+  const gap = ' '.repeat(gapSize);
+
+  // Render Straight-Line Layout (Flawless f and i separation)
+  console.log(gray(' ──────────────────────────────────────────────────────────────────'));
+  console.log(`  ${leftText}${gap}${rightText}`);
+  console.log(gray(' ──────────────────────────────────────────────────────────────────'));
+}
+const HELP_SECTION_INDENT = 2;
+const HELP_ROW_INDENT = 5;
+const HELP_COMMAND_WIDTH = 38;
+
+export function printHelpFooter() {
+  console.log('');
+  console.log(boxTop(brandDark));
+  console.log(
+    boxCenterLine(`${accent('◆')} ${boldWhite('Command Reference')}`, brandDark)
+  );
+  console.log(boxBottom(brandDark));
+
+  const section = (title) => {
+    console.log('');
+    console.log(' '.repeat(HELP_SECTION_INDENT) + brandBold(title));
+  };
+
+  section('⚡ Interactive Mode');
+  helpRow('sf', 'Launch interactive mode');
+
+  section('🚀 Project Creation');
+  helpRow('sf new <appName> react ts grid', 'Create a new Syncfusion project');
+
+  section('🧩 Component Commands');
+  helpRow('sf add grid', 'Add a Grid sample');
+  helpRow('sf add chart', 'Add a Chart sample');
+  helpRow('sf add scheduler', 'Add a Scheduler sample');
+  helpRow('sf add gantt', 'Add a Gantt sample');
+  helpRow('sf add file-manager', 'Add a File Manager sample');
+  helpRow('sf add diagram', 'Add a Diagram sample');
+  helpRow('sf add rich-text-editor', 'Add a Rich Text Editor sample');
+  helpRow('sf add pdf-viewer', 'Add a PDF Viewer sample');
+  helpRow('sf add docx-editor', 'Add a DOCX Editor sample');
+  helpRow('sf add spreadsheet-editor', 'Add a Spreadsheet Editor sample');
+
+  section('🤖 AI & MCP');
+  helpRow('sf mcp init [editor]', 'Configure the Syncfusion MCP server for your editor');
+  helpRow('sf skills install', 'Install the Syncfusion component skills');
+
+  // section('↑ Upgrade');
+  // helpRow('sf upgrade', 'Update installed Syncfusion packages to latest');
+
+  section('🎨 Theme Management');
+  helpRow('sf theme switch [themeName]', 'Switch the active Syncfusion theme');
+
+  section('ℹ️ Project Information');
+  helpRow('sf info', 'Show environment & project information');
+
+  const framework = getProjectFramework();
+  const docsLink = getDocumentationLink(framework);
+  console.log('');
+  console.log('');
+  console.log(boxTop(brandDark));
+  console.log(
+    boxLine(`  ${gray('Docs')} ${accent('-')} ${cyan(docsLink)}`, brandDark)
+  );
+  console.log(boxBottom(brandDark));
+  console.log('');
+}
+
+function helpRow(usage, desc) {
+  const command = usage.padEnd(HELP_COMMAND_WIDTH);
+  console.log(`${' '.repeat(HELP_ROW_INDENT)}${brand(command)} ${gray(desc)}`);
+}
+
+function getProjectFramework(projectDir = process.cwd()) {
+  const configPath = path.join(projectDir, 'syncfusion.config.json');
+  if (!fs.existsSync(configPath)) {
+    return 'react';
+  }
+  try {
+    const configText = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(configText);
+    const framework = String(config.framework || '').trim().toLowerCase();
+
+    if (['react', 'angular', 'vue'].includes(framework)) {
+      return framework;
+    }
+    return 'react';
+  } catch {
+    return 'react';
+  }
+}
+
+function getDocumentationLink(framework) {
+  const docsLinks = {
+    react: 'https://ej2.syncfusion.com/react/documentation/introduction',
+    angular: 'https://ej2.syncfusion.com/angular/documentation/introduction',
+    vue: 'https://ej2.syncfusion.com/vue/documentation/introduction'
+  };
+
+  return docsLinks[framework] || docsLinks.react;
+}

package/src/utils/common.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { access, readFile } from 'node:fs/promises';
+import { TEMPLATE_PACKAGES } from '../constants.js';
+import { addPackagesToJson } from './package-manager.js';
+
+export async function pathExists(targetPath) {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function addTemplatePackages(appPath, selectedTemplate, frameworkKey) {
+  const emptyPackages = TEMPLATE_PACKAGES.empty?.[frameworkKey] || [];
+  const componentPackages = TEMPLATE_PACKAGES[selectedTemplate]?.[frameworkKey] || [];
+  const packages = [
+    ...emptyPackages,
+    ...componentPackages
+  ];
+  if (!packages.length) {
+    return;
+  }
+  await addPackagesToJson(appPath, packages);
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export async function updateVersions(root, packages) {
+  const packageJsonPath = path.join(root, 'package.json');
+  const packageJson = await readJson(packageJsonPath);
+  if (!packageJson) {
+    return packages;
+  }
+  const dependencies = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {})
+  };
+  const existingThemePackageName = Object.keys(dependencies).find(
+    (packageName) => /^@syncfusion\/ej2-.+-theme$/.test(packageName)
+  );
+  if (!existingThemePackageName) {
+    return packages;
+  }
+  const version = dependencies[existingThemePackageName];
+
+  return packages.map((packageName) => {
+    if (
+      !packageName.startsWith('@syncfusion/ej2-') ||
+      packageName.lastIndexOf('@') > 0
+    ) {
+      return packageName;
+    }
+
+    return `${packageName}@${version}`;
+  });
+}

package/src/utils/config-generator.js

@@ -0,0 +1,73 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from './logger.js';
+import packageJson from '../../package.json' with { type: 'json' };
+import { pathExists } from './common.js';
+
+export async function generateSyncfusionConfig(appPath, options) {
+  try {
+    const template = options.template || 'empty';
+    const config = {
+      framework: options.framework || 'react',
+      type: options.type || 'typescript',
+      theme: options.theme || 'material3',
+      styling: options.styling || 'css',
+      template,
+      buildTool: options.buildTool || null,
+      // Tracks every routed component present in the project (used by `sf add`).
+      components: template === 'empty' ? [] : [template],
+      mcp: { integrated: false, editors: [] },
+      skills: { installed: false },
+      version: packageJson.version,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      syncfusionVersion: packageJson.version
+    };
+
+    const configPath = path.join(appPath, 'syncfusion.config.json');
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+
+    return config;
+  } catch (error) {
+    logger.error(`Failed to generate config: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Path to the syncfusion.config.json for a given project root.
+ */
+export function getConfigPath(appPath) {
+  return path.join(appPath, 'syncfusion.config.json');
+}
+
+/**
+ * Read syncfusion.config.json from a project root. Returns null if it doesn't exist
+ * or can't be parsed.
+ */
+export async function readSyncfusionConfig(appPath) {
+  const configPath = getConfigPath(appPath);
+  try {
+    if (!(await pathExists(configPath))) return null;
+    return JSON.parse(await readFile(configPath, 'utf8'));
+  } catch (error) {
+    logger.warning(`Could not read syncfusion.config.json: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Shallow-merge `patch` into the existing syncfusion.config.json (creating a
+ * minimal one if it doesn't exist yet) and persist it back to disk.
+ */
+export async function updateSyncfusionConfig(appPath, patch = {}) {
+  const configPath = getConfigPath(appPath);
+  const existing = (await readSyncfusionConfig(appPath)) || {};
+  const merged = {
+    ...existing,
+    ...patch,
+    updatedAt: new Date().toISOString()
+  };
+  await writeFile(configPath, JSON.stringify(merged, null, 2));
+  return merged;
+}

package/src/utils/folder-structure.js

@@ -0,0 +1,26 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from './logger.js';
+
+export async function createProjectFolderStructure(appPath, template = 'empty') {
+  try {
+    // Base folders - always create these
+    const baseFolders = [
+      path.join(appPath, 'src')
+    ];
+
+    // Additional folders - only for non-empty templates
+    const additionalFolders = template !== 'empty' ? [
+      path.join(appPath, 'src', 'components')
+    ] : [];
+
+    const allFolders = [...baseFolders, ...additionalFolders];
+
+    for (const folder of allFolders) {
+      await mkdir(folder, { recursive: true });
+    }
+  } catch (error) {
+    logger.error(`Failed to create folder structure: ${error.message}`);
+    throw error;
+  }
+}

package/src/utils/logger.js

@@ -0,0 +1,19 @@
+import { ansi, wrap } from './ansi-colors.js';
+
+export const logger = {
+  info(message) {
+    console.log(wrap(message, ansi.blue));
+  },
+
+  success(message) {
+    console.log(wrap(message, ansi.green));
+  },
+
+  warning(message) {
+    console.log(wrap(message, ansi.yellow));
+  },
+
+  error(message) {
+    console.log(wrap(message, ansi.red));
+  }
+};

package/src/utils/mcp-generator.js

@@ -0,0 +1,122 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from './logger.js';
+import { MCP_ASSISTANT_PACKAGES } from '../constants.js';
+import { pathExists } from './common.js';
+
+const EDITOR_CONFIGS = {
+  vscode: { configDir: '.vscode', configFile: 'mcp.json', rootKey: 'servers', includeType: true },
+  cursor: { configDir: '.cursor', configFile: 'mcp.json', rootKey: 'mcpServers', includeType: false },
+  codestudio: { configDir: '.codestudio', configFile: 'mcp.json', rootKey: 'servers', includeType: true },
+  jetbrains: { configDir: '.jetbrains', configFile: 'mcp.json', rootKey: 'mcpServers', includeType: false, command: process.platform === 'win32' ? 'npx.cmd' : 'npx' }
+};
+
+const EDITOR_ALIASES = {
+  vscode: 'vscode',
+  'vs-code': 'vscode',
+  vsCode: 'vscode',
+  cursor: 'cursor',
+  codestudio: 'codestudio',
+  codeStudio: 'codestudio',
+  'code-studio': 'codestudio',
+  jetbrains: 'jetbrains',
+  jetBrains: 'jetbrains'
+};
+
+function normalizeEditor(editorKey) {
+  return EDITOR_ALIASES[editorKey] || editorKey;
+}
+
+function getAssistantPackage(framework) {
+  return MCP_ASSISTANT_PACKAGES[framework] || MCP_ASSISTANT_PACKAGES.react;
+}
+
+function serverName(framework) {
+  return `sf-${framework}-mcp`;
+}
+
+function buildServerBlock(framework, editorConfig) {
+  const serverBlock = {
+    command: editorConfig.command || 'npx',
+    args: ['-y', `${getAssistantPackage(framework)}@latest`],
+    env: {
+      // eslint-disable-next-line camelcase
+      Syncfusion_API_Key_Path: 'YOUR_API_KEY_FILE_PATH'
+    }
+  };
+
+  if (editorConfig.includeType) {
+    return {
+      type: 'stdio',
+      ...serverBlock
+    };
+  }
+
+  return serverBlock;
+}
+
+export async function writeMcpJson(appPath, framework, editorKey) {
+  const normalizedEditor = normalizeEditor(editorKey);
+  const editorConfig = EDITOR_CONFIGS[normalizedEditor];
+
+  if (!editorConfig) {
+    return null;
+  }
+
+  const configDir = path.join(appPath, editorConfig.configDir);
+  const configPath = path.join(configDir, editorConfig.configFile);
+
+  await mkdir(configDir, { recursive: true });
+
+  let existing = {};
+  if (await pathExists(configPath)) {
+    try {
+      existing = JSON.parse(await readFile(configPath, 'utf8'));
+    } catch {
+      existing = {};
+    }
+  }
+
+  const rootKey = editorConfig.rootKey;
+  const merged = {
+    ...existing,
+    [rootKey]: {
+      ...(existing[rootKey] || {}),
+      [serverName(framework)]: buildServerBlock(framework, editorConfig)
+    }
+  };
+
+  await writeFile(configPath, JSON.stringify(merged, null, 2));
+  return path.relative(appPath, configPath);
+}
+
+
+export async function setupMcpForEditors(appPath, framework, editorKeys = ['all']) {
+  const normalizedKeys = editorKeys.map(normalizeEditor);
+  const keys = normalizedKeys.includes('all')
+    ? ['vscode', 'cursor', 'codestudio', 'jetbrains']
+    : normalizedKeys;
+
+  const written = [];
+
+  for (const key of keys) {
+    const relPath = await writeMcpJson(appPath, framework, key);
+    if (relPath) {
+      written.push(key);
+    }
+  }
+
+  return written;
+}
+
+export async function applyMcpIntegration(appPath, framework, editorKeys) {
+  const keys = Array.isArray(editorKeys) ? editorKeys : ['all'];
+  const written = await setupMcpForEditors(appPath, framework, keys);
+
+  if (written.length > 0) {
+    logger.success('\n✅ MCP server configuration added.');
+    logger.info(`Update the configuration file with your Syncfusion API key, then open the file(s) and click "Start" to connect to the MCP server. \nFor more information, see: https://ej2.syncfusion.com/${framework}/documentation/mcp-server/ai-coding-assistant/getting-started`);
+  }
+
+  return { integrated: written.length > 0, editors: written };
+}

package/src/utils/package-manager.js

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { pathExists } from './common.js';
+
+export const DEFAULT_SYNCFUSION_VERSION = '34.2.2';
+
+async function readJsonFile(filePath) {
+  return JSON.parse(await readFile(filePath, 'utf8'));
+}
+
+async function writeJsonFile(filePath, data) {
+  await writeFile(filePath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Detect which package manager the project uses, based on lockfiles.
+ * Defaults to npm.
+ */
+export async function detectPackageManager(appPath) {
+  if (await pathExists(path.join(appPath, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (await pathExists(path.join(appPath, 'yarn.lock'))) return 'yarn';
+  if (await pathExists(path.join(appPath, 'bun.lockb'))) return 'bun';
+  return 'npm';
+}
+
+/**
+ * Return the install command/args for a given package manager, used to
+ * (re)install dependencies, e.g. `npm install`.
+ */
+export function getInstallCommand(pkgManager) {
+  switch (pkgManager) {
+    case 'yarn':
+      return { command: 'yarn', args: ['install'] };
+    case 'pnpm':
+      return { command: 'pnpm', args: ['install'] };
+    case 'bun':
+      return { command: 'bun', args: ['install'] };
+    default:
+      return { command: 'npm', args: ['install'] };
+  }
+}
+
+/**
+ * Return the command/args to upgrade one or more packages to latest, for the
+ * given package manager.
+ */
+export function getUpgradeCommand(pkgManager, packages, version = 'latest') {
+  const versionRange = version === 'latest' ? 'latest' : normalizeSyncfusionVersion(version);
+  const targets = packages.map((p) => `${p}@${versionRange}`);
+  switch (pkgManager) {
+    case 'yarn':
+      return { command: 'yarn', args: ['add', ...targets] };
+    case 'pnpm':
+      return { command: 'pnpm', args: ['add', ...targets] };
+    case 'bun':
+      return { command: 'bun', args: ['add', ...targets] };
+    default:
+      return { command: 'npm', args: ['install', ...targets] };
+  }
+}
+
+/**
+ * Read package.json from a project root and return every @syncfusion/*
+ * dependency (name -> version string) found in dependencies/devDependencies.
+ */
+export async function getSyncfusionPackages(appPath) {
+  const packageJsonPath = path.join(appPath, 'package.json');
+  if (!(await pathExists(packageJsonPath))) return {};
+
+  const packageJson = await readJsonFile(packageJsonPath);
+  const deps = { ...(packageJson.dependencies || {}), ...(packageJson.devDependencies || {}) };
+
+  return Object.fromEntries(
+    Object.entries(deps).filter(([name]) => name.startsWith('@syncfusion/'))
+  );
+}
+
+function normalizeSyncfusionVersion(version = DEFAULT_SYNCFUSION_VERSION) {
+  const normalized = String(version || DEFAULT_SYNCFUSION_VERSION)
+    .trim()
+    .replace(/^--/, '')
+    .replace(/^~/, '');
+
+  return normalized === 'latest' ? 'latest' : `~${normalized}`;
+}
+
+function splitPackageSpec(pkg) {
+  const lastAtIndex = pkg.lastIndexOf('@');
+
+  if (pkg.startsWith('@') && lastAtIndex === 0) {
+    return { name: pkg, version: undefined };
+  }
+
+  if (lastAtIndex > 0) {
+    return {
+      name: pkg.substring(0, lastAtIndex),
+      version: pkg.substring(lastAtIndex + 1)
+    };
+  }
+
+  return { name: pkg, version: undefined };
+}
+
+function resolvePackageVersion(name, version, syncfusionVersion) {
+  if (name.startsWith('@syncfusion/')) {
+    return normalizeSyncfusionVersion(version || syncfusionVersion);
+  }
+
+  return version || '*';
+}
+
+export async function addPackagesToJson(appPath, packages) {
+  if (!packages.length) return;
+
+  const packageJsonPath = path.join(appPath, 'package.json');
+  const packageJson = await readJsonFile(packageJsonPath);
+  packageJson.dependencies = packageJson.dependencies || {};
+
+  // Add packages to dependencies. Syncfusion packages are pinned with the
+  // default tilde range, for example: "@syncfusion/ej2-react-grids": "~34.2.2".
+  // Non-Syncfusion packages continue to use their specified version or "*".
+  for (const pkg of packages) {
+    const { name, version } = splitPackageSpec(pkg);
+    packageJson.dependencies[name] = resolvePackageVersion(name, version, DEFAULT_SYNCFUSION_VERSION);
+  }
+
+  await writeJsonFile(packageJsonPath, packageJson);
+}