vk-typescript-cli 1.0.0

package/src/utils/project-bootstrap.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import { confirm } from '../../lib/inquirer-prompts.js';
+import { logger } from './logger.js';
+import { runCommand } from './run-command.js';
+import { detectPackageManager, getInstallCommand } from './package-manager.js';
+import { safePrompt } from './prompt-utils.js';
+import { pathExists } from './common.js';
+
+/**
+ * Resolve the dev-server command + args for a freshly created project, based
+ * on framework / build tool.
+ */
+export function getDevCommand(framework, buildTool) {
+  if (framework === 'angular') return { command: 'npm', args: ['run', 'start'] };
+  if (buildTool === 'nextjs') return { command: 'npm', args: ['run', 'dev'] };
+  return { command: 'npm', args: ['run', 'dev'] };
+}
+
+/**
+ * Print the standard "Next steps" block. Used when the user declines to
+ * install/start automatically.
+ */
+export function printNextSteps(appName, framework, buildTool) {
+  const dev = getDevCommand(framework, buildTool);
+  const devString = framework === 'angular' ? 'ng serve' : `${dev.command} ${dev.args.join(' ')}`;
+
+
+  logger.info(`\n📖 Next steps:`);
+  logger.info(`   cd ${appName}`);
+  logger.info(`   npm install`);
+  logger.info(`   ${devString}\n`);
+}
+
+/**
+ * After scaffolding, ask: "Install dependencies and start now?" unless
+ * `skip` is true (e.g. --yes / non-TTY / programmatic invocation). When
+ * yes, runs install in `appPath` and then starts the dev server (which keeps
+ * the process attached — exit with Ctrl+C).
+ *
+ * Returns { installed: boolean, started: boolean } for callers that want to
+ * record the result (e.g. into syncfusion.config.json).
+ */
+export async function promptAndBootstrap(appPath, appName, framework, buildTool, { skip = false, force = false } = {}) {
+  if (skip) {
+    printNextSteps(appName, framework, buildTool);
+    return { installed: false, started: false };
+  }
+
+  // Don't prompt when there is no interactive terminal (e.g. CI).
+  if (!process.stdout.isTTY) {
+    printNextSteps(appName, framework, buildTool);
+    return { installed: false, started: false };
+  }
+
+  if (!force) {
+    const wantsBootstrap = await safePrompt(confirm, {
+      message: '📦 Install dependencies and start the dev server now?',
+      default: true
+    });
+    if (!wantsBootstrap) {
+      printNextSteps(appName, framework, buildTool);
+      return { installed: false, started: false };
+    }
+  }
+
+  // 1) Install
+  const pkgManager = await detectPackageManager(appPath);
+  const { command: instCmd, args: instArgs } = getInstallCommand(pkgManager);
+  logger.info(`\n📦 Installing dependencies with ${pkgManager} (this can take a minute)...\n`);
+  try {
+    await runCommand(instCmd, instArgs, { cwd: appPath });
+  } catch (error) {
+    logger.error(`❌ Install failed: ${error.message}`);
+    printNextSteps(appName, framework, buildTool);
+    return { installed: false, started: false };
+  }
+  logger.success('\n✅ Dependencies installed.\n');
+
+  // 2) Start the dev server (blocks until the user kills it with Ctrl+C)
+  const dev = getDevCommand(framework, buildTool);
+  const hasNodeModules = await pathExists(path.join(appPath, 'node_modules'));
+  if (!hasNodeModules) {
+    logger.warning('⚠️  node_modules is still missing — skipping dev server start.');
+    printNextSteps(appName, framework, buildTool);
+    return { installed: true, started: false };
+  }
+
+  logger.info(`🚀 Starting dev server (${dev.command} ${dev.args.join(' ')})...\n`);
+  logger.info('   Press Ctrl+C to stop.\n');
+  try {
+    await runCommand(dev.command, dev.args, { cwd: appPath });
+  } catch (error) {
+    // Dev server exiting (Ctrl+C, port-in-use, etc.) is non-fatal.
+    logger.error(`❌ Dev Server failed: ${error.message}`);
+  }
+
+  return { installed: true, started: true };
+}

package/src/utils/project-detector.js

@@ -0,0 +1,195 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readSyncfusionConfig } from './config-generator.js';
+import { logger } from './logger.js';
+
+const THEME_PACKAGE_TO_NAME = {
+  '@syncfusion/ej2-tailwind3-theme': 'tailwind3',
+  '@syncfusion/ej2-bootstrap5.3-theme': 'bootstrap5.3',
+  '@syncfusion/ej2-fluent2-theme': 'fluent2',
+  '@syncfusion/ej2-material3-theme': 'material3'
+};
+
+/**
+ * Walk upward from `startDir` looking for a file/folder that indicates a
+ * project root (package.json). Returns the directory or null if not found.
+ */
+function findProjectRoot(startDir, markerFile = 'package.json', maxDepth = 6) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i <= maxDepth; i++) {
+    if (existsSync(path.join(dir, markerFile))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function detectFrameworkFromPackageJson(pkgJson) {
+  const deps = { ...(pkgJson.dependencies || {}), ...(pkgJson.devDependencies || {}) };
+
+  if (deps['@angular/core']) return 'angular';
+  if (deps['vue']) return 'vue';
+  if (deps['react']) return 'react';
+  // The TypeScript (vanilla EJ2) platform is identified by the presence of
+  // a core Syncfusion EJ2 package such as `@syncfusion/ej2-grids`, with no
+  // framework wrapper (no react/angular/vue dependencies).
+  const hasSyncfusionCore = Object.keys(deps).some(
+    (name) => /^@syncfusion\/ej2-[a-z0-9-]+$/.test(name)
+  );
+  if (hasSyncfusionCore && !deps['@angular/core'] && !deps['vue'] && !deps['react']) {
+    return 'typescript';
+  }
+  return null;
+}
+
+function detectBuildTool(pkgJson, framework) {
+  if (framework !== 'react') return null;
+  const deps = { ...(pkgJson.dependencies || {}), ...(pkgJson.devDependencies || {}) };
+  return deps['next'] ? 'nextjs' : 'vite';
+}
+
+function detectLanguage(rootPath) {
+  return existsSync(path.join(rootPath, 'tsconfig.json')) ? 'typescript' : 'javascript';
+}
+
+function detectStyle(pkgJson) {
+  const deps = { ...(pkgJson.dependencies || {}), ...(pkgJson.devDependencies || {}) };
+  return deps['sass'] ? 'scss' : 'css';
+}
+
+function detectTheme(pkgJson) {
+  const deps = { ...(pkgJson.dependencies || {}), ...(pkgJson.devDependencies || {}) };
+  for (const [pkg, theme] of Object.entries(THEME_PACKAGE_TO_NAME)) {
+    if (deps[pkg]) return theme;
+  }
+  return 'material3';
+}
+
+function detectComponentsFromDisk(rootPath, framework) {
+  const found = [];
+  const componentsDir = path.join(rootPath, 'src', 'components');
+  if (!existsSync(componentsDir)) return found;
+
+  const checks = {
+    grid: framework === 'angular' ? 'grid' : /^Grid\.(jsx|tsx|vue|js|ts)$/,
+    chart: framework === 'angular' ? 'chart' : /^Chart\.(jsx|tsx|vue|js|ts)$/,
+    scheduler: framework === 'angular' ? 'scheduler' : /^Scheduler\.(jsx|tsx|vue|js|ts)$/,
+    gantt: framework === 'angular' ? 'gantt' : /^Gantt\.(jsx|tsx|vue|js|ts)$/,
+    'file-manager': framework === 'angular' ? 'file-manager' : /^FileManager\.(jsx|tsx|vue|js|ts)$/,
+    diagram: framework === 'angular' ? 'diagram' : /^Diagram\.(jsx|tsx|vue|js|ts)$/,
+    'rich-text-editor': framework === 'angular' ? 'rich-text-editor' : /^RTE\.(jsx|tsx|vue|js|ts)$/,
+    'pdf-viewer': framework === 'angular' ? 'pdf-viewer' : /^PDFViewer\.(jsx|tsx|vue|js|ts)$/,
+    'docx-editor': framework === 'angular' ? 'docx-editor' : /^DOCXEditor\.(jsx|tsx|vue|js|ts)$/,
+    'spreadsheet-editor': framework === 'angular' ? 'spreadsheet-editor' : /^SpreadsheetEditor\.(jsx|tsx|vue|js|ts)$/
+  };
+
+  const entries = readdirSync(componentsDir);
+  for (const [key, matcher] of Object.entries(checks)) {
+    if (framework === 'angular') {
+      if (entries.includes(matcher)) found.push(key);
+    } else if (entries.some((e) => matcher.test(e))) {
+      found.push(key);
+    }
+  }
+  return found;
+}
+
+/**
+ * Detect the Syncfusion project rooted at (or above) `cwd`.
+ *
+ * Resolution order:
+ *  1. `syncfusion.config.json` (authoritative, written by this CLI).
+ *  2. Best-effort detection from package.json + tsconfig.json + node_modules.
+ *
+ * Returns `null` when no package.json can be found at all (i.e. not inside
+ * any Node project).
+ */
+export async function detectProject(cwd = process.cwd()) {
+  const root = findProjectRoot(cwd);
+  if (!root) return null;
+
+  let pkgJson = {};
+  try {
+    pkgJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  } catch {
+    pkgJson = {};
+  }
+
+  const config = await readSyncfusionConfig(root);
+
+  if (config) {
+    return {
+      root,
+      framework: config.framework,
+      type: config.type,
+      styling: config.styling || 'css',
+      theme: config.theme,
+      buildTool: config.buildTool || null,
+      template: config.template || 'empty',
+      components: config.components || [],
+      appName: pkgJson.name || path.basename(root),
+      fromConfig: true,
+      config
+    };
+  }
+
+  // Fall back to best-effort detection.
+  const framework = detectFrameworkFromPackageJson(pkgJson);
+  if (!framework) {
+    return {
+      root,
+      framework: null,
+      appName: pkgJson.name || path.basename(root),
+      fromConfig: false,
+      config: null
+    };
+  }
+
+  const components = detectComponentsFromDisk(root, framework);
+
+  return {
+    root,
+    framework,
+    // The TypeScript (vanilla EJ2) platform is always TypeScript.
+    type: framework === 'typescript' ? 'typescript' : detectLanguage(root),
+    styling: detectStyle(pkgJson),
+    theme: detectTheme(pkgJson),
+    buildTool: detectBuildTool(pkgJson, framework),
+    template: components[0] || 'empty',
+    components,
+    appName: pkgJson.name || path.basename(root),
+    fromConfig: false,
+    config: null
+  };
+}
+
+/**
+ * Detect the project, or print a friendly error and return null.
+ */
+export async function requireSyncfusionProject(cwd = process.cwd()) {
+  const project = await detectProject(cwd);
+
+  if (!project) {
+    logger.error('❌ No package.json found. Run this command inside a project folder.');
+    return null;
+  }
+
+  if (!project.framework) {
+    logger.error(
+      '❌ Could not detect a Syncfusion project created with @syncfusion/syncfusion-cli. This command only works inside projects scaffolded using @syncfusion/syncfusion-cli.'
+    );
+    logger.info('');
+    logger.info('Quick fix:');
+    logger.info('   1. Navigate to your project folder (e.g. cd my-app)');
+    logger.info('   2. Re-run the command');
+    logger.info('');
+    logger.info('Or scaffold a new project:');
+    logger.info('     sf new my-app');
+    return null;
+  }
+  return project;
+}

package/src/utils/prompt-utils.js

@@ -0,0 +1,29 @@
+import { select } from '../../lib/inquirer-prompts.js';
+
+export async function safePrompt(promptFn, config) {
+  try {
+    return await promptFn(config);
+  } catch (error) {
+    if (error?.name === 'ExitPromptError') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export const SELECT_OPTION_INDENT = '  ';
+
+export function withIndentedChoices(choices) {
+  return choices.map((choice) => ({
+    ...choice,
+    name: `${SELECT_OPTION_INDENT}${choice.name}`,
+    short: choice.short || choice.name
+  }));
+}
+
+export async function selectWithIndentedChoices(config) {
+  return safePrompt(select, {
+    ...config,
+    choices: withIndentedChoices(config.choices)
+  });
+}

package/src/utils/run-command.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+const WINDOWS_SHIM_COMMANDS = new Set(['npm', 'npx', 'pnpm', 'yarn']);
+
+function isWindows() {
+  return process.platform === 'win32';
+}
+
+function normalizeArgs(args) {
+  if (!args) {
+    return [];
+  }
+  if (Array.isArray(args)) {
+    return args;
+  }
+
+  return [String(args)];
+}
+
+function isWindowsShim(command) {
+  return isWindows() && /\.(cmd|bat)$/i.test(command);
+}
+
+function resolveWindowsCommand(command) {
+  if (!command || typeof command !== 'string') {
+    throw new TypeError('Command must be a non-empty string');
+  }
+  if (!isWindows()) {
+    return command;
+  }
+  const commandName = path.basename(command).toLowerCase();
+  if (WINDOWS_SHIM_COMMANDS.has(commandName)) {
+    return `${command}.cmd`;
+  }
+
+  return command;
+}
+
+function getSpawnCommand(command, args) {
+  const normalizedArgs = normalizeArgs(args);
+  const resolvedCommand = resolveWindowsCommand(command);
+  if (isWindowsShim(resolvedCommand)) {
+    return {
+      command: 'cmd.exe',
+      args: ['/d', '/s', '/c', resolvedCommand, ...normalizedArgs]
+    };
+  }
+
+  return {
+    command: resolvedCommand,
+    args: normalizedArgs
+  };
+}
+
+function runCommand(command, args = [], options = {}) {
+  const { capture = false, ...spawnOptions } = options;
+  const {
+    command: effectiveCommand,
+    args: effectiveArgs
+  } = getSpawnCommand(command, args);
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(effectiveCommand, effectiveArgs, {
+      cwd: spawnOptions.cwd,
+      env: spawnOptions.env,
+      shell: false,
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit'
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (capture) {
+      child.stdout?.on('data', (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+    child.on('error', (error) => {
+      error.command = effectiveCommand;
+      error.args = effectiveArgs;
+      reject(error);
+    });
+    child.on('exit', (code, signal) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const message =
+        stderr.trim() ||
+        (signal
+          ? `Command terminated with signal ${signal}`
+          : `Command exited with code ${code}`);
+      const error = new Error(message);
+      error.code = code;
+      error.signal = signal;
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.command = effectiveCommand;
+      error.args = effectiveArgs;
+      reject(error);
+    });
+  });
+}
+
+export { runCommand };
+export default runCommand;

package/src/utils/skills-installer.js

@@ -0,0 +1,69 @@
+import { select, confirm } from '../../lib/inquirer-prompts.js';
+import { runCommand } from './run-command.js';
+import { logger } from './logger.js';
+import { SKILLS_PACKAGES } from '../constants.js';
+import { safePrompt } from './prompt-utils.js';
+
+export async function promptSkillsInstallMode() {
+  const mode = await safePrompt(select, {
+    message: 'How do you want to install Syncfusion Component Skills?',
+    choices: [
+      { name: 'Install all skills', value: 'all' },
+      { name: 'Install selected skills', value: 'selected' }
+    ],
+    default: 'all'
+  });
+
+  if (!mode) {
+    logger.warning('\n⚠️  Skills installation cancelled.\n');
+    return null;
+  }
+
+  return mode;
+}
+
+/**
+ * Run `npx skills add <package>` for the given framework inside `appPath`.
+ * By default, `-y` is used to install all skills/non-interactive selection.
+ * When `allSkills` is false, `-y` is not passed so the skills CLI can ask for selected skills.
+ */
+export async function installSkills(appPath, framework, { allSkills = true } = {}) {
+  const pkg = SKILLS_PACKAGES[framework] || SKILLS_PACKAGES.react;
+  const args = ['skills', 'add', pkg];
+
+  if (allSkills) {
+    args.push('-y');
+  }
+
+  logger.info(`\n📦 Installing Syncfusion ${framework} component skills (npx ${args.join(' ')})...`);
+
+  try {
+    await runCommand('npx', args, { cwd: appPath });
+
+    logger.success('✅ Syncfusion component skills installed.\n');
+    return true;
+  } catch (error) {
+    const fallbackCommand = `npx skills add ${pkg}${allSkills ? ' -y' : ''}`;
+    logger.warning(`⚠️  Could not install skills automatically (${error.message}).`);
+    logger.info(`   You can install them later by running:\n   ${fallbackCommand}\n`);
+    return false;
+  }
+}
+
+/**
+ * Interactive prompt flow: "Want to install Syncfusion component skills?"
+ * Skips entirely when `skip` is true (e.g. --yes flag).
+ */
+export async function promptAndInstallSkills(appPath, framework, { skip = false } = {}) {
+  if (skip) return { installed: false };
+
+  const wantsSkills = await safePrompt(confirm, {
+    message: '🧠 Want to install Syncfusion component skills for AI coding agents?',
+    default: false
+  });
+
+  if (!wantsSkills) return { installed: false };
+
+  const installed = await installSkills(appPath, framework);
+  return { installed };
+}

package/src/utils/template-file.js

@@ -0,0 +1,35 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// templates/ is a sibling of utils/ under src/
+export const TEMPLATES_ROOT = path.resolve(__dirname, '..', 'templates');
+
+/**
+ * Copy a single template file from `src/templates/<framework>/<name>`
+ * to `<destDir>/<name>` inside the user's project.
+ */
+export async function copyTemplateFile(framework, name, destDir) {
+  const sourcePath = path.join(TEMPLATES_ROOT, framework, name);
+  const destPath = path.join(destDir, name);
+
+  await mkdir(destDir, { recursive: true });
+  await copyFile(sourcePath, destPath);
+}
+
+/**
+ * Copy every file in a framework subfolder (e.g. all files for an Angular
+ * component that has a .ts + .html pair) — given by the explicit list of
+ * file names. We iterate the list so we don't need a real subfolder on disk
+ * for each Angular component.
+ */
+export async function copyTemplateFiles(framework, files, srcDir, destDir) {
+  const sourceDir = path.join(TEMPLATES_ROOT, framework, srcDir);
+  await mkdir(destDir, { recursive: true });
+  for (const name of files) {
+    await copyFile(path.join(sourceDir, name), path.join(destDir, name));
+  }
+}

package/src/utils/theme-loader.js

@@ -0,0 +1,47 @@
+export const THEME_MAP = {
+  'tailwind3': {
+    package: '@syncfusion/ej2-tailwind3-theme',
+    path: 'tailwind3'
+  },
+  'bootstrap5.3': {
+    package: '@syncfusion/ej2-bootstrap5.3-theme',
+    path: 'bootstrap5.3'
+  },
+  'fluent2': {
+    package: '@syncfusion/ej2-fluent2-theme',
+    path: 'fluent2'
+  },
+  'material3': {
+    package: '@syncfusion/ej2-material3-theme',
+    path: 'material3'
+  }
+};
+
+export async function getThemePackages(theme) {
+  const themeConfig = THEME_MAP[theme] || THEME_MAP.material3;
+
+  return {
+    base: themeConfig.package,
+    themePath: `../node_modules/${themeConfig.package}/styles/${themeConfig.path}`
+  };
+}
+
+export function generateThemeImportStatement(theme, styling = 'css') {
+  const themeConfig = THEME_MAP[theme] || THEME_MAP.material3;
+  if (styling === 'scss') {
+    return `@use "${themeConfig.package}/styles/${themeConfig.path}.scss" as *;`;
+  }
+  else {
+    return `@import "${themeConfig.package}/styles/${themeConfig.path}.css";`;
+  }
+}
+
+export function generateMainThemeImportStatement(theme, styling = 'css') {
+  const themeConfig = THEME_MAP[theme] || THEME_MAP.material3;
+  if (styling === 'scss') {
+    return `import "${themeConfig.package}/styles/${themeConfig.path}.scss";`;
+  }
+  else {
+    return `import "${themeConfig.package}/styles/${themeConfig.path}.css";`;
+  }
+}