@thinkwise/testwise 0.2.0-beta.3 → 0.2.5

package/scripts/sync.js

@@ -1,69 +1,756 @@
-
 /* eslint-disable @typescript-eslint/naming-convention */
 
 import { execSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { ArtifactManager } from '../dist/artifact-builder/index.js';
+import { PathResolver } from '../dist/helpers/index.js';
+import { indiciumApi } from '../dist/services/IndiciumApi.service.js';
+
+// ============================================================================
+// Constants & Configuration
+// ============================================================================
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** @type {Readonly<{ROOT: string, DIST: string, SEED_DATA: string, TEST_ARTIFACTS: string, TEMP_TEST_ARTIFACTS: string, TEMPLATE_TEST_ARTIFACTS: string}>} */
+const PATHS = Object.freeze({
+  ROOT: path.resolve(__dirname, '..'),
+  DIST: path.resolve(__dirname, '..', 'dist'),
+  SEED_DATA: path.resolve(__dirname, '..', 'seed-data'),
+  TEST_ARTIFACTS: path.resolve(__dirname, '..', 'test-artifacts'),
+  TEMP_TEST_ARTIFACTS: path.resolve(__dirname, '..', 'test-artifacts-temp'),
+  TEMPLATE_TEST_ARTIFACTS: path.resolve(__dirname, '..', 'templates', 'test-artifacts')
+});
+
+/** @type {readonly string[]} */
+const REQUIRED_SEED_FILES = Object.freeze(['screensToBuild.json', 'subjectsToBuild.json']);
+
+/** @type {Readonly<{CLEANUP: string, BUILD: string, REFINE: string, GENERATE: string, COMPILE: string, BACKUP: string}>} */
+const PHASE_NAMES = Object.freeze({
+  CLEANUP: 'Cleanup and Initial Compilation',
+  BUILD: 'Build Model Data',
+  REFINE: 'Refine Model Data',
+  GENERATE: 'Generate Artifacts',
+  COMPILE: 'Final Compilation',
+  BACKUP: 'Backup'
+});
+
+/** @type {Readonly<{INFO: string, SUCCESS: string, ERROR: string, WARNING: string, PHASE: string, STEP: string, DIVIDER: string}>} */
+const LOG_SYMBOLS = Object.freeze({
+  INFO: 'ℹ️',
+  SUCCESS: '✅',
+  ERROR: '❌',
+  WARNING: '⚠️',
+  PHASE: '📦',
+  STEP: '▸',
+  DIVIDER: '═'
+});
+
+// ============================================================================
+// Types & Interfaces
+// ============================================================================
+
+/**
+ * @typedef {Object} SyncContext
+ * @property {import('../dist/artifact-builder/helpers/index.js').Stopwatch} stopwatch - Stopwatch instance for timing
+ * @property {ReturnType<import('../dist/artifact-builder/helpers/index.js').Stopwatch['start']>} totalTimer - Total elapsed timer
+ * @property {AbortSignal} [signal] - Optional abort signal for graceful shutdown
+ * @property {SyncOptions} options - Sync configuration options
+ */
+
+/**
+ * @typedef {Object} SyncOptions
+ * @property {boolean} [dryRun=false] - If true, only logs what would happen without executing
+ * @property {boolean} [verbose=false] - If true, enables verbose logging
+ * @property {boolean} [skipBackup=false] - If true, skips the backup phase
+ * @property {number} [retryAttempts=0] - Number of retry attempts for failed operations
+ * @property {number} [retryDelay=1000] - Delay in ms between retry attempts
+ */
+
+/**
+ * @typedef {Object} StepResult
+ * @property {boolean} success - Whether the step succeeded
+ * @property {number} duration - Duration in milliseconds
+ * @property {Error} [error] - Error if step failed
+ */
+
+// ============================================================================
+// Logger Utility
+// ============================================================================
+
+/**
+ * Centralized logging utility with consistent formatting.
+ */
+const Logger = {
+  /**
+   * Logs an informational message.
+   * @param {string} message - The message to log
+   */
+  info(message) {
+    console.info(`${LOG_SYMBOLS.INFO}  ${message}`);
+  },
+
+  /**
+   * Logs a success message.
+   * @param {string} message - The message to log
+   */
+  success(message) {
+    console.info(`${LOG_SYMBOLS.SUCCESS} ${message}`);
+  },
+
+  /**
+   * Logs an error message.
+   * @param {string} message - The message to log
+   * @param {Error} [error] - Optional error object
+   */
+  error(message, error) {
+    console.error(`${LOG_SYMBOLS.ERROR} ${message}`);
+    if (error?.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+  },
+
+  /**
+   * Logs a warning message.
+   * @param {string} message - The message to log
+   */
+  warn(message) {
+    console.warn(`${LOG_SYMBOLS.WARNING}  ${message}`);
+  },
+
+  /**
+   * Logs a phase header.
+   * @param {number} phaseNumber - The phase number
+   * @param {string} phaseName - The phase name
+   */
+  phase(phaseNumber, phaseName) {
+    console.info(`\n${LOG_SYMBOLS.PHASE} Phase ${phaseNumber}: ${phaseName}\n`);
+  },
+
+  /**
+   * Logs a step execution.
+   * @param {string} stepName - The step name
+   */
+  step(stepName) {
+    console.info(`  ${LOG_SYMBOLS.STEP} ${stepName}`);
+  },
+
+  /**
+   * Logs a divider line.
+   * @param {number} [width=60] - The width of the divider
+   */
+  divider(width = 60) {
+    console.info(LOG_SYMBOLS.DIVIDER.repeat(width));
+  },
+
+  /**
+   * Logs a header with dividers.
+   * @param {string} message - The header message
+   */
+  header(message) {
+    this.divider();
+    console.info(message);
+    this.divider();
+  }
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Sleeps for the specified duration.
+ * @param {number} ms - Duration in milliseconds
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Executes a function with retry logic.
+ * @template T
+ * @param {() => Promise<T> | T} fn - The function to execute
+ * @param {number} [attempts=3] - Number of retry attempts
+ * @param {number} [delay=1000] - Delay between retries in ms
+ * @returns {Promise<T>}
+ */
+async function withRetry(fn, attempts = 3, delay = 1000) {
+  let lastError;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt < attempts) {
+        Logger.warn(`Attempt ${attempt}/${attempts} failed, retrying in ${delay}ms...`);
+        await sleep(delay);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Safely cleans a directory without deleting the root folder
+ * to avoid EPERM errors during npm postinstall.
+ * @param {string} dirPath - The directory path to clean
+ * @returns {void}
+ */
+function safeCleanDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return;
+  }
+
+  // Rename test-artifacts to temp directory if needed (only once)
+  if (fs.existsSync(PATHS.TEST_ARTIFACTS) && !fs.existsSync(PATHS.TEMP_TEST_ARTIFACTS)) {
+    fs.renameSync(PATHS.TEST_ARTIFACTS, PATHS.TEMP_TEST_ARTIFACTS);
+    fs.cpSync(PATHS.TEMPLATE_TEST_ARTIFACTS, PATHS.TEST_ARTIFACTS, { recursive: true });
+  }
+
+  const files = fs.readdirSync(dirPath);
+  for (const file of files) {
+    const filePath = path.join(dirPath, file);
+    try {
+      fs.rmSync(filePath, { recursive: true, force: true });
+    } catch (error) {
+      Logger.warn(`Could not remove ${filePath}: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Ensures a JSON file exists to prevent ENOENT crashes
+ * if the Refiner doesn't handle missing files gracefully.
+ * @param {string} filePath - The file path to ensure exists
+ * @param {unknown} [defaultContent=[]] - Default content to write if file doesn't exist
+ * @returns {void}
+ */
+function ensureJsonExists(filePath, defaultContent = []) {
+  if (fs.existsSync(filePath)) {
+    return;
+  }
+
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(defaultContent, null, 2));
+}
 
-const _filename = fileURLToPath(import.meta.url);
-const _dirname = path.dirname(_filename);
+/**
+ * Validates that all required dependencies and directories exist.
+ * @throws {Error} If validation fails
+ * @returns {void}
+ */
+function validateEnvironment() {
+  // Ensure seed-data directory exists
+  if (!fs.existsSync(PATHS.SEED_DATA)) {
+    fs.mkdirSync(PATHS.SEED_DATA, { recursive: true });
+  }
 
-export async function sync() {
+  // Verify TypeScript config exists
+  const tsconfigPath = path.join(PATHS.ROOT, 'tsconfig.json');
+  if (!fs.existsSync(tsconfigPath)) {
+    throw new Error('tsconfig.json not found. Please ensure the project is properly set up.');
+  }
+}
 
+/**
+ * Executes a TypeScript compilation.
+ * @param {string} cwd - The working directory
+ * @throws {Error} If compilation fails
+ * @returns {void}
+ */
+function compileTypeScript(cwd) {
   try {
-    const rootDir = path.resolve(_dirname, '..');
+    execSync('npx tsc', { cwd, stdio: 'inherit' });
+  } catch (error) {
+    throw new Error(`TypeScript compilation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Resets the SubjectRegistry.ts file from template.
+ * @returns {void}
+ */
+function resetSubjectRegistry() {
+  const registryPath = path.join(PATHS.ROOT, 'page-extensions', 'SubjectRegistry.ts');
+  const templatePath = path.join(PATHS.ROOT, 'templates', 'SubjectRegistry.template.ts');
+
+  if (fs.existsSync(registryPath)) {
+    fs.rmSync(registryPath, { force: true });
+  }
+
+  if (fs.existsSync(templatePath)) {
+    fs.copyFileSync(templatePath, registryPath);
+  }
+}
+
+/**
+ * Cleans up temporary test artifacts directory.
+ * @returns {void}
+ */
+function cleanupTempArtifacts() {
+  if (fs.existsSync(PATHS.TEMP_TEST_ARTIFACTS)) {
+    fs.rmSync(PATHS.TEMP_TEST_ARTIFACTS, { recursive: true, force: true });
+  }
+}
 
-    const { rimrafSync } = await import('rimraf');
+// ============================================================================
+// Sync Pipeline Steps
+// ============================================================================
 
-    // Remove dist folder synchronously
-    rimrafSync(path.join(rootDir, 'dist'));
+/**
+ * Runs a single sync step with timing and optional dry-run support.
+ * @param {SyncContext} ctx - The sync context
+ * @param {string} stepName - Name of the step
+ * @param {() => Promise<void> | void} fn - The function to execute
+ * @returns {Promise<StepResult>}
+ */
+async function runStep(ctx, stepName, fn) {
+  Logger.step(stepName);
 
-    // Compile TypeScript
-    execSync('npx tsc', { cwd: rootDir, stdio: 'inherit' });
+  if (ctx.options.dryRun) {
+    return { success: true, duration: 0 };
+  }
 
-    // Lazy import post recompilation
-    const { InterfaceGenerator } = await import('../dist/artifact-builder/index.js');
-    const { ScreenInterfaceRefiner } = await import('../dist/artifact-builder/index.js');
-    const { SchemaGenerator } = await import('../dist/artifact-builder/index.js');
-    const { SubjectComponentGenerator } = await import('../dist/artifact-builder/index.js');
-    const { SubjectGenerator } = await import('../dist/artifact-builder/index.js');
-    const { ModelDataRefiner } = await import('../dist/artifact-builder/index.js');
-    const { buildSubjects, buildScreens } = await import('../dist/artifact-builder/ModelDataBuilder.js');
-    // const { SubjectRegistration } = await import('../dist/artifact-builder/index.js'); - do not remove: future feature
+  const timer = ctx.stopwatch.start(stepName);
+  const startTime = Date.now();
+
+  try {
+    // Check for abort signal
+    if (ctx.signal?.aborted) {
+      throw new Error('Sync process was aborted');
+    }
 
-    // Build Seed Data Axios Instance
+    const execute =
+      ctx.options.retryAttempts > 0 ? () => withRetry(fn, ctx.options.retryAttempts, ctx.options.retryDelay) : fn;
+
+    await execute();
+
+    return { success: true, duration: Date.now() - startTime };
+  } catch (error) {
+    return { success: false, duration: Date.now() - startTime, error };
+  } finally {
+    timer.stop();
+  }
+}
+
+/**
+ * Phase 1: Cleanup and initial compilation
+ * @param {SyncContext} ctx - The sync context
+ * @returns {Promise<void>}
+ */
+async function phaseCleanupAndCompile(ctx) {
+  Logger.phase(1, PHASE_NAMES.CLEANUP);
+
+  resetSubjectRegistry();
+
+  const cleanResult = await runStep(ctx, 'Clear distribution directory', () => {
+    safeCleanDir(PATHS.DIST);
+  });
+
+  if (!cleanResult.success) {
+    throw cleanResult.error;
+  }
+
+  const compileResult = await runStep(ctx, 'Recompile TypeScript sources', () => {
+    compileTypeScript(PATHS.ROOT);
+  });
+
+  if (!compileResult.success) {
+    throw compileResult.error;
+  }
+}
+
+/**
+ * Phase 2: Build model data
+ * @param {SyncContext} ctx - The sync context
+ * @returns {Promise<void>}
+ */
+async function phaseBuildModelData(ctx) {
+  Logger.phase(2, PHASE_NAMES.BUILD);
+
+  const { buildSubjects, buildScreens } = await import('../dist/artifact-builder/ModelDataBuilder.js');
+
+  const subjectsResult = await runStep(ctx, 'Build subjects from model data', async () => {
     await buildSubjects();
+  });
+
+  if (!subjectsResult.success) {
+    throw subjectsResult.error;
+  }
+
+  const screensResult = await runStep(ctx, 'Build screens from model data', async () => {
     await buildScreens();
+  });
+
+  if (!screensResult.success) {
+    throw screensResult.error;
+  }
+}
 
-    // Seed data refinement pre-processing
+/**
+ * Phase 3: Refine model data
+ * @param {SyncContext} ctx - The sync context
+ * @returns {Promise<void>}
+ */
+async function phaseRefineModelData(ctx) {
+  Logger.phase(3, PHASE_NAMES.REFINE);
+
+  // Ensure required seed files exist before refinement
+  for (const seedFile of REQUIRED_SEED_FILES) {
+    ensureJsonExists(path.join(PATHS.SEED_DATA, seedFile));
+  }
+
+  const { ModelDataRefiner } = await import('../dist/artifact-builder/index.js');
+
+  const refineResult = await runStep(ctx, 'Refine model data', async () => {
     await new ModelDataRefiner().run();
-    
+  });
+
+  if (!refineResult.success) {
+    throw refineResult.error;
+  }
+}
+
+/**
+ * Phase 4: Generate artifacts
+ * @param {SyncContext} ctx - The sync context
+ * @returns {Promise<void>}
+ */
+async function phaseGenerateArtifacts(ctx) {
+  Logger.phase(4, PHASE_NAMES.GENERATE);
+
+  const {
+    InterfaceGenerator,
+    ScreenInterfaceRefiner,
+    SchemaGenerator,
+    SubjectComponentGenerator,
+    SubjectGenerator,
+    SubjectRegistration
+  } = await import('../dist/artifact-builder/index.js');
+
+  const interfaceGenerator = new InterfaceGenerator();
 
-    // Generate artifacts
-    const interfaceGenerator = new InterfaceGenerator();
+  /** @type {Array<{name: string, fn: () => Promise<void> | void}>} */
+  const steps = [
+    {
+      name: 'Generate screen interfaces from screen schemas',
+      fn: () => interfaceGenerator.generateScreenInterfacesFromSchemas()
+    },
+    {
+      name: 'Refine interfaces',
+      fn: () => new ScreenInterfaceRefiner().refine()
+    },
+    {
+      name: 'Generate subject component schemas',
+      fn: () => new SchemaGenerator().generateSchema()
+    },
+    {
+      name: 'Generate subject component interfaces from schemas',
+      fn: () => interfaceGenerator.generateSubjectInterfacesFromSchemas()
+    },
+    {
+      name: 'Build components that implement interfaces',
+      fn: () => new SubjectComponentGenerator().run()
+    },
+    {
+      name: 'Generate subject classes',
+      fn: () => new SubjectGenerator().run()
+    },
+    {
+      name: 'Add subjects to registry',
+      fn: async () => await new SubjectRegistration().run()
+    }
+  ];
 
-    await interfaceGenerator.generateScreenInterfacesFromSchemas();
+  for (const step of steps) {
+    const result = await runStep(ctx, step.name, step.fn);
+    if (!result.success) {
+      throw result.error;
+    }
+  }
+}
+
+/**
+ * Phase 5: Final compilation
+ * @param {SyncContext} ctx - The sync context
+ * @returns {Promise<void>}
+ */
+async function phaseFinalCompilation(ctx) {
+  Logger.phase(5, PHASE_NAMES.COMPILE);
 
-    new ScreenInterfaceRefiner().refine();
-    new SchemaGenerator().generateSchema();
+  const cleanResult = await runStep(ctx, 'Clear distribution directory', () => {
+    safeCleanDir(PATHS.DIST);
+  });
+
+  if (!cleanResult.success) {
+    throw cleanResult.error;
+  }
 
-    await interfaceGenerator.generateSubjectInterfacesFromSchemas();
+  const compileResult = await runStep(ctx, 'Compile generated artifacts', () => {
+    compileTypeScript(PATHS.ROOT);
+  });
+
+  if (!compileResult.success) {
+    throw compileResult.error;
+  }
+}
+
+/**
+ * Phase 6: Backup
+ * @param {SyncContext} ctx - The sync context
+ * @returns {Promise<void>}
+ */
+async function phaseBackup(ctx) {
+  if (ctx.options.skipBackup) {
+    Logger.info('Skipping backup phase (--skip-backup flag)');
+    return;
+  }
+
+  Logger.phase(6, PHASE_NAMES.BACKUP);
+
+  const { ArtifactManager } = await import('../dist/artifact-builder/index.js');
+
+  const backupResult = await runStep(ctx, 'Perform backup', () => {
+    new ArtifactManager().performBackup();
+    cleanupTempArtifacts();
+  });
+
+  if (!backupResult.success) {
+    throw backupResult.error;
+  }
+}
+
+// ============================================================================
+// Main Sync Function
+// ============================================================================
+
+/**
+ * Parses command line arguments into sync options.
+ * @returns {SyncOptions}
+ */
+function parseCommandLineArgs() {
+  const args = process.argv.slice(2);
+
+  return {
+    dryRun: args.includes('--dry-run'),
+    verbose: args.includes('--verbose') || args.includes('-v'),
+    skipBackup: args.includes('--skip-backup'),
+    retryAttempts: parseInt(args.find((arg) => arg.startsWith('--retry='))?.split('=')[1] ?? '0', 10),
+    retryDelay: parseInt(args.find((arg) => arg.startsWith('--retry-delay='))?.split('=')[1] ?? '1000', 10)
+  };
+}
+
+/**
+ * Sets up graceful shutdown handlers.
+ * @param {AbortController} controller - The abort controller
+ * @returns {void}
+ */
+function setupShutdownHandlers(controller) {
+  const shutdown = () => {
+    Logger.warn('Received shutdown signal, attempting graceful shutdown...');
+    controller.abort();
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
 
-    new SubjectComponentGenerator().run();
-    new SubjectGenerator().run();
-    // new SubjectRegistration().run(); - do not remove: future feature
+/**
+ * Executes the complete synchronization process.
+ *
+ * This process:
+ * 1. Cleans the dist directory and compiles TypeScript
+ * 2. Builds model data from subjects and screens
+ * 3. Refines the model data
+ * 4. Generates all artifacts (interfaces, schemas, components, subjects)
+ * 5. Performs final compilation
+ * 6. Creates a backup
+ *
+ * @param {SyncOptions} [options={}] - Optional sync configuration
+ * @returns {Promise<void>}
+ * @throws {Error} If sync process fails
+ */
+export async function sync(options = {}) {
+  // Merge provided options with command line args (CLI takes precedence)
+  const cliOptions = parseCommandLineArgs();
+  const mergedOptions = { ...options, ...cliOptions };
 
-    // Compile TypeScript again
-    execSync('npx tsc', { cwd: rootDir, stdio: 'inherit' });
+  // Setup abort controller for graceful shutdown
+  const abortController = new AbortController();
+  setupShutdownHandlers(abortController);
 
-    console.info('Sync process completed successfully.');
+  // Late import to avoid circular dependency issues during initial compile
+  const { Stopwatch } = await import('../dist/artifact-builder/helpers/index.js');
+
+  const stopwatch = new Stopwatch();
+  const totalTimer = stopwatch.start('Sync process start to end');
+
+  /** @type {SyncContext} */
+  const ctx = {
+    stopwatch,
+    totalTimer,
+    signal: abortController.signal,
+    options: mergedOptions
+  };
+
+  Logger.header('🚀 Starting Testwise Sync Process');
+
+  if (mergedOptions.dryRun) {
+    Logger.warn('Running in DRY RUN mode - no changes will be made');
+  }
+
+  if (mergedOptions.verbose) {
+    Logger.info(`Options: ${JSON.stringify(mergedOptions, null, 2)}`);
+  }
+
+  // Model data verification before any sync steps
+  if (!(await verifiedModelData())) {
+    Logger.info('Model data verification failed. Sync aborted.');
+    process.exit(0);
+  }
+
+  try {
+    // Pre-flight validation
+    validateEnvironment();
+
+    // Execute phases in sequence
+    await phaseCleanupAndCompile(ctx);
+    await phaseBuildModelData(ctx);
+    await phaseRefineModelData(ctx);
+    await phaseGenerateArtifacts(ctx);
+    await phaseFinalCompilation(ctx);
+
+    Logger.header('✅ Sync process completed successfully!');
   } catch (error) {
-    // reinstate the backup --  simulate this to see what happens first
-    console.error('Sync process failed:', error.message);
-    process.exit(1); // Will npm do an automatic rollback here?
+    Logger.divider();
+    Logger.error('Sync process failed!', error);
+    Logger.divider();
+    process.exit(1);
   } finally {
-    new ArtifactManager().performBackup();
+    try {
+      await phaseBackup(ctx);
+    } catch (backupError) {
+      Logger.warn(`Backup failed: ${backupError.message}`);
+    }
+
+    totalTimer.stop();
+  }
+}
+
+/**
+ * Verify that model data is properly configured
+ * @returns {Promise<boolean>} True if model data is verified, false otherwise
+ */
+async function verifiedModelData() {
+  try {
+    const consumerRoot = new PathResolver().getConsumerRootDirectory();
+    const seedDataDir = path.join(consumerRoot, 'seed-data');
+    const subjectsJson = path.join(seedDataDir, 'subjects.json');
+    const screensDir = path.join(seedDataDir, 'screen-schemas');
+    const projectIsConfigured = await isConfigured();
+
+    // Check if seed-data directory exists
+    if (!fs.existsSync(seedDataDir)) {
+      return handleMissingSeedDataDirectory(seedDataDir, screensDir, projectIsConfigured);
+    }
+
+    // Check if subjects.json exists
+    if (!fs.existsSync(subjectsJson) && !projectIsConfigured) {
+      Logger.info('Required file not found: subjects.json');
+      return false;
+    }
+
+    // Check if screens directory exists
+    if (!fs.existsSync(screensDir)) {
+      return handleMissingScreensDirectory(screensDir, projectIsConfigured);
+    }
+
+    // Check if there are any screen files
+    const screenFiles = fs.readdirSync(screensDir).filter((f) => f.endsWith('.json'));
+    if (screenFiles.length === 0 && !projectIsConfigured) {
+      Logger.info('No screen JSON files found in seed-data/screen-schemas');
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    Logger.error('Model data verification error:', error);
+    return false;
+  }
+}
+
+/**
+ * Handle missing seed-data directory
+ * @param {string} seedDataDir - Path to seed-data directory
+ * @param {string} screensDir - Path to screens directory
+ * @param {boolean} projectIsConfigured - Whether project is configured
+ * @returns {boolean} True if handled successfully, false otherwise
+ */
+function handleMissingSeedDataDirectory(seedDataDir, screensDir, projectIsConfigured) {
+  if (projectIsConfigured) {
+    try {
+      fs.mkdirSync(seedDataDir, { recursive: true });
+      fs.mkdirSync(screensDir, { recursive: true });
+      Logger.info('Created seed-data directory structure.');
+      return true;
+    } catch (error) {
+      Logger.error('Failed to create seed-data directory:', error);
+      return false;
+    }
+  }
+
+  Logger.info('No seed-data directory found.');
+  return false;
+}
+
+/**
+ * Handle missing screens directory
+ * @param {string} screensDir - Path to screens directory
+ * @param {boolean} projectIsConfigured - Whether project is configured
+ * @returns {boolean} True if handled successfully, false otherwise
+ */
+function handleMissingScreensDirectory(screensDir, projectIsConfigured) {
+  if (projectIsConfigured) {
+    try {
+      fs.mkdirSync(screensDir, { recursive: true });
+      Logger.info('Created screen-schemas directory.');
+      return true;
+    } catch (error) {
+      Logger.error('Failed to create screen-schemas directory:', error);
+      return false;
+    }
+  }
+
+  Logger.info('No screen-schemas directory found.');
+  return false;
+}
+
+/**
+ * Check if project is configured with valid credentials
+ * @returns {Promise<boolean>} True if project is configured, false otherwise
+ */
+async function isConfigured() {
+  try {
+    if (typeof indiciumApi.canConnect === 'function') {
+      return await indiciumApi.canConnect();
+    }
+    if (typeof indiciumApi.canConnectToProject === 'function') {
+      return await indiciumApi.canConnectToProject();
+    }
+    Logger.warn('No valid connection check found on indiciumApi.');
+    return false;
+  } catch (error) {
+    Logger.error('Configuration check failed:', error);
+    return false;
   }
 }