@qelos/plugins-cli 0.0.14 → 0.0.16

package/cli.mjs

@@ -10,6 +10,7 @@ import createCommand from './commands/create.mjs';
 import pushCommand from './commands/push.mjs';
 import pullCommand from './commands/pull.mjs';
 import generateCommand from './commands/generate.mjs';
+import blueprintsCommand from './commands/blueprints.mjs';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const program = yargs(hideBin(process.argv));
@@ -26,5 +27,6 @@ createCommand(program)
 pushCommand(program)
 pullCommand(program)
 generateCommand(program)
+blueprintsCommand(program)
 
 program.help().argv;

package/commands/blueprints.mjs

@@ -0,0 +1,28 @@
+import blueprintsController from "../controllers/blueprints.mjs";
+
+export default function blueprintsCommand(program) {
+  program
+    .command('blueprints generate [path]', 'generate new blueprints from actual database tables/collections',
+      (yargs) => {
+        return yargs
+          .positional('path', {
+            describe: 'Path to store the pulled resources.',
+            type: 'string',
+            default: './blueprints',
+            required: false
+          })
+          .option('uri', {
+            describe: 'The URI of the database. Defaults to mongodb://localhost:27017/db',
+            type: 'string',
+            required: false,
+            default: 'mongodb://localhost:27017/db'
+          })
+          .option('guides', {
+            describe: 'Generate SDK guides for each blueprint',
+            type: 'boolean',
+            required: false,
+            default: true
+          })
+      },
+      blueprintsController)
+}

package/controllers/blueprints.mjs

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { logger } from "../services/logger.mjs";
+import {
+  SUPPORTED_PROTOCOL,
+  generateBlueprintsFromMongo,
+} from "../services/blueprint-generator.mjs";
+
+export default async function blueprintsController({ uri, path: targetPath, guides = true }) {
+  const connectionUri = uri || "mongodb://localhost:27017/db";
+
+  if (!SUPPORTED_PROTOCOL.test(connectionUri)) {
+    logger.error("Only mongodb:// URIs are supported at the moment.");
+    process.exit(1);
+  }
+
+  const targetDir = path.join(process.cwd(), targetPath);
+  const shouldGenerateGuides = guides !== false;
+
+  try {
+    await generateBlueprintsFromMongo({
+      uri: connectionUri,
+      targetDir,
+      createGuides: shouldGenerateGuides,
+    });
+  } catch {
+    process.exit(1);
+  }
+}

package/controllers/create.mjs

@@ -2,7 +2,7 @@ import follow from "follow-redirects";
 import cliSelect from "cli-select";
 import { blue } from "../utils/colors.mjs";
 import DecompressZip from "decompress-zip";
-import { join } from "path";
+import { join } from "node:path";
 import { rimraf } from "rimraf";
 import ProgressBar from "../utils/progress-bar.mjs";
 import * as readline from "node:readline";

package/controllers/generate.mjs

@@ -1,7 +1,5 @@
 import { generateRules } from '../services/generate-rules.mjs';
 import { logger } from '../services/logger.mjs';
-import path from 'node:path';
-import fs from 'node:fs';
 
 export default async function generateController({ type }) {
   try {

package/controllers/push.mjs

@@ -17,10 +17,16 @@ export default async function pushController({ type, path: sourcePath }) {
       process.exit(1);
     }
 
-    // Validate path is a directory
-    if (!fs.statSync(sourcePath).isDirectory()) {
-      logger.error(`Path is not a directory: ${sourcePath}`);
-      logger.info('Please provide a directory path, not a file');
+    const stat = fs.statSync(sourcePath);
+    let basePath = sourcePath;
+    let targetFile = null;
+
+    if (stat.isFile()) {
+      basePath = path.dirname(sourcePath);
+      targetFile = path.basename(sourcePath);
+      logger.info(`Detected file path. Only pushing ${targetFile}`);
+    } else if (!stat.isDirectory()) {
+      logger.error(`Path must be a file or directory: ${sourcePath}`);
       process.exit(1);
     }
 
@@ -28,6 +34,10 @@ export default async function pushController({ type, path: sourcePath }) {
 
     // Handle "all" or "*" type
     if (type === 'all' || type === '*') {
+      if (targetFile) {
+        logger.error('Cannot push "all" using a single file. Please provide a directory path.');
+        process.exit(1);
+      }
       logger.section(`Pushing all resources from ${sourcePath}`);
       
       const types = [
@@ -39,7 +49,7 @@ export default async function pushController({ type, path: sourcePath }) {
       ];
 
       for (const { name, fn } of types) {
-        const typePath = path.join(sourcePath, name);
+        const typePath = path.join(basePath, name);
         
         // Skip if directory doesn't exist
         if (!fs.existsSync(typePath)) {
@@ -60,18 +70,18 @@ export default async function pushController({ type, path: sourcePath }) {
       return;
     }
 
-    logger.section(`Pushing ${type} from ${sourcePath}`);
+    logger.section(`Pushing ${type} from ${targetFile ? `${basePath} (${targetFile})` : basePath}`);
 
     if (type === 'components') {
-      await pushComponents(sdk, sourcePath);
+      await pushComponents(sdk, basePath, { targetFile });
     } else if (type === 'blueprints') {
-      await pushBlueprints(sdk, sourcePath);
+      await pushBlueprints(sdk, basePath, { targetFile });
     } else if (type === 'plugins') {
-      await pushPlugins(sdk, sourcePath);
+      await pushPlugins(sdk, basePath, { targetFile });
     } else if (type === 'blocks') {
-      await pushBlocks(sdk, sourcePath);
+      await pushBlocks(sdk, basePath, { targetFile });
     }  else if (type === 'config' || type === 'configs' || type === 'configuration') {
-      await pushConfigurations(sdk, sourcePath);
+      await pushConfigurations(sdk, basePath, { targetFile });
     } else {
       logger.error(`Unknown type: ${type}`);
       logger.info('Supported types: components, blueprints, plugins, blocks, config, configs, configuration, all');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/plugins-cli",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "CLI to manage QELOS plugins",
   "main": "cli.mjs",
   "bin": {
@@ -20,6 +20,7 @@
     "decompress-zip": "^0.3.3",
     "follow-redirects": "^1.15.11",
     "jiti": "^2.6.1",
+    "mongodb": "^7.0.0",
     "rimraf": "^6.0.1",
     "yargs": "^18.0.0",
     "zx": "^8.8.5"

package/services/blocks.mjs

@@ -17,12 +17,18 @@ function toKebabCase(str) {
  * @param {Object} sdk - Initialized SDK instance
  * @param {string} path - Path to blocks directory
  */
-export async function pushBlocks(sdk, path) {
-  const files = fs.readdirSync(path);
+export async function pushBlocks(sdk, path, options = {}) {
+  const { targetFile } = options;
+  const directoryFiles = fs.readdirSync(path);
+  const files = targetFile ? [targetFile] : directoryFiles;
   const blockFiles = files.filter(f => f.endsWith('.html'));
   
   if (blockFiles.length === 0) {
-    logger.warning(`No .html files found in ${path}`);
+    if (targetFile) {
+      logger.warning(`File ${targetFile} is not an .html block. Skipping.`);
+    } else {
+      logger.warning(`No .html files found in ${path}`);
+    }
     return;
   }
   

package/services/blueprint-generator.mjs

@@ -0,0 +1,247 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MongoClient } from 'mongodb';
+import { logger } from './logger.mjs';
+import { generateSdkGuide } from './blueprint-sdk-guides.mjs';
+import {
+  formatTitle,
+  toIdentifier,
+  ensureSingular,
+  detectBlueprintType,
+  mapBlueprintTypeToJsonSchema
+} from './blueprint-shared.mjs';
+
+export const SUPPORTED_PROTOCOL = /^mongodb:\/\//i;
+const SAMPLE_SIZE = 50;
+
+export async function generateBlueprintsFromMongo({ uri, targetDir, createGuides = true }) {
+  ensureDirectory(targetDir);
+  const client = new MongoClient(uri, { serverSelectionTimeoutMS: 10_000 });
+
+  try {
+    await client.connect();
+    const dbName = getDatabaseName(uri);
+    const db = client.db(dbName);
+
+    logger.section(`Connected to MongoDB database: ${db.databaseName}`);
+
+    const collections = await db.listCollections().toArray();
+    const filteredCollections = collections.filter(({ name }) => !name.startsWith('system.'));
+
+    if (filteredCollections.length === 0) {
+      logger.warning('No collections found to generate blueprints from.');
+      return;
+    }
+
+    for (const collection of filteredCollections) {
+      await generateBlueprintForCollection({
+        db,
+        collectionName: collection.name,
+        targetDir,
+        createGuides,
+      });
+    }
+
+    logger.success(`Generated ${filteredCollections.length} blueprint file(s) in ${targetDir}`);
+  } catch (error) {
+    logger.error('Failed to generate blueprints', error);
+    throw error;
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+async function generateBlueprintForCollection({ db, collectionName, targetDir, createGuides }) {
+  logger.step(`Analyzing collection: ${collectionName}`);
+  try {
+    const collection = db.collection(collectionName);
+    const documents = await sampleCollectionDocuments(collection);
+    const properties = buildProperties(collectionName, documents);
+
+    const blueprint = createBlueprintPayload(collectionName, properties);
+    const blueprintPath = path.join(targetDir, `${blueprint.identifier}.blueprint.json`);
+
+    fs.writeFileSync(blueprintPath, JSON.stringify(blueprint, null, 2));
+    logger.success(`Blueprint generated: ${blueprintPath}`);
+
+    if (createGuides) {
+      generateSdkGuide({ blueprint, documents, targetDir });
+    }
+  } catch (error) {
+    logger.error(`Failed to process collection ${collectionName}`, error);
+  }
+}
+
+function buildProperties(collectionName, documents) {
+  const properties = {};
+  let processedDocuments = 0;
+
+  for (const doc of documents) {
+    if (processedDocuments >= SAMPLE_SIZE) {
+      break;
+    }
+    processedDocuments += 1;
+    if (!doc || typeof doc !== 'object') continue;
+
+    for (const [key, value] of Object.entries(doc)) {
+      if (shouldSkipField(key) || properties[key]) continue;
+      properties[key] = createPropertyDescriptor(key, value, collectionName);
+    }
+  }
+
+  if (Object.keys(properties).length === 0) {
+    logger.warning(
+      `No properties detected for collection ${collectionName}. Generated blueprint will contain empty properties.`
+    );
+  }
+
+  return properties;
+}
+
+function createPropertyDescriptor(key, sampleValue, collectionName) {
+  const { normalizedValue, multi } = normalizeSampleValue(sampleValue);
+  const type = detectBlueprintType(normalizedValue);
+
+  const descriptor = {
+    title: formatTitle(key),
+    type,
+    description: '',
+    required: false
+  };
+
+  if (multi) {
+    descriptor.multi = true;
+  }
+
+  if (type === 'object') {
+    descriptor.schema = buildObjectSchema(normalizedValue);
+  }
+
+  return descriptor;
+}
+
+function normalizeSampleValue(value) {
+  if (Array.isArray(value)) {
+    const firstValue = value.find((item) => item !== null && item !== undefined);
+    return { normalizedValue: firstValue ?? null, multi: true };
+  }
+
+  return { normalizedValue: value, multi: false };
+}
+
+function createBlueprintPayload(collectionName, properties) {
+  const singularName = ensureSingular(collectionName);
+  return {
+    identifier: toIdentifier(singularName),
+    name: formatTitle(singularName),
+    description: `Auto-generated blueprint for MongoDB collection "${collectionName}"`,
+    entityIdentifierMechanism: 'objectid',
+    permissions: createDefaultPermissions(),
+    permissionScope: 'workspace',
+    properties,
+    relations: [],
+    dispatchers: {
+      create: false,
+      update: false,
+      delete: false
+    },
+    limitations: []
+  };
+}
+
+function createDefaultPermissions() {
+  const operations = ['create', 'read', 'update', 'delete'];
+  return operations.map((operation) => ({
+    scope: 'workspace',
+    operation,
+    guest: false,
+    roleBased: ['*'],
+    workspaceRoleBased: ['*'],
+    workspaceLabelsBased: ['*']
+  }));
+}
+
+async function sampleCollectionDocuments(collection) {
+  try {
+    return await collection.aggregate([{ $sample: { size: SAMPLE_SIZE } }]).toArray();
+  } catch (error) {
+    logger.debug(`Falling back to sequential sampling for ${collection.collectionName}: ${error.message}`);
+    return collection.find({}).limit(SAMPLE_SIZE).toArray();
+  }
+}
+
+function buildObjectSchema(sample, depth = 0) {
+  const MAX_SCHEMA_DEPTH = 3;
+  if (!sample || typeof sample !== 'object' || depth >= MAX_SCHEMA_DEPTH) {
+    return { type: 'object' };
+  }
+
+  const properties = {};
+
+  for (const [key, value] of Object.entries(sample)) {
+    if (key === '_id' || value === undefined) continue;
+    properties[key] = buildSchemaFromValue(value, depth + 1);
+  }
+
+  if (Object.keys(properties).length === 0) {
+    return { type: 'object' };
+  }
+
+  return {
+    type: 'object',
+    properties
+  };
+}
+
+function buildSchemaFromValue(value, depth) {
+  if (Array.isArray(value)) {
+    const arraySample = value.find((item) => item !== null && item !== undefined);
+    const itemsSchema = arraySample ? buildSchemaFromValue(arraySample, depth + 1) : { type: 'string' };
+    return {
+      type: 'array',
+      items: itemsSchema
+    };
+  }
+
+  const valueType = detectBlueprintType(value);
+
+  if (valueType === 'object' && value && typeof value === 'object') {
+    return buildObjectSchema(value, depth + 1);
+  }
+
+  return {
+    type: mapBlueprintTypeToJsonSchema(valueType)
+  };
+}
+
+function shouldSkipField(key) {
+  if (!key) return true;
+  const normalized = key.toLowerCase();
+  if (
+    normalized === '_id' ||
+    normalized === 'id' ||
+    normalized === 'user' ||
+    normalized === 'userid' ||
+    normalized === 'workspace' ||
+    normalized === 'workspaceid'
+  ) {
+    return true;
+  }
+  return key.startsWith('__');
+}
+
+function ensureDirectory(targetDir) {
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    logger.info(`Created output directory at ${targetDir}`);
+  }
+}
+
+function getDatabaseName(connectionUri) {
+  try {
+    const parsed = new URL(connectionUri);
+    return parsed.pathname.replace(/^\//, '') || undefined;
+  } catch {
+    return undefined;
+  }
+}

package/services/blueprint-sdk-guides.mjs

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatTitle, detectBlueprintType } from './blueprint-shared.mjs';
+
+export function generateSdkGuide({ blueprint, documents, targetDir }) {
+  const guidePath = path.join(targetDir, `${blueprint.identifier}.sdk.md`);
+  const interfaceName = `${formatTitle(blueprint.identifier).replace(/\s+/g, '')}Entity`;
+  const entityVarName = `${toCamelCase(blueprint.identifier)}Entities`;
+  const sampleDoc = documents.find((doc) => doc && typeof doc === 'object');
+  const interfaceDefinition = buildInterfaceDefinition(interfaceName, blueprint);
+  const exampleEntity = buildExampleEntity(blueprint, sampleDoc);
+  const exampleLiteral = stringifyObjectLiteral(exampleEntity);
+
+  const markdown = buildMarkdown({
+    blueprint,
+    interfaceName,
+    entityVarName,
+    interfaceDefinition,
+    exampleLiteral,
+  });
+
+  fs.writeFileSync(guidePath, markdown);
+  return guidePath;
+}
+
+function buildMarkdown({ blueprint, interfaceName, entityVarName, interfaceDefinition, exampleLiteral }) {
+  return [
+    `# ${blueprint.name} Blueprint SDK Guide`,
+    '',
+    '## Install the SDK',
+    '```bash',
+    'npm install @qelos/sdk',
+    '```',
+    '',
+    '## Initialize the Administrator SDK',
+    '```ts',
+    "import QelosAdministratorSDK from '@qelos/sdk/administrator';",
+    '',
+    'const sdk = new QelosAdministratorSDK({',
+    "  appUrl: process.env.QELOS_URL || 'http://localhost:3000',",
+    '  fetch,',
+    '});',
+    '',
+    `const ${entityVarName} = sdk.blueprints.entitiesOf<${interfaceName}>('${blueprint.identifier}');`,
+    '```',
+    '',
+    '## TypeScript Interface',
+    '```ts',
+    interfaceDefinition,
+    '```',
+    '',
+    '## Example Entity Payload',
+    '```ts',
+    `const sample${interfaceName} = ${exampleLiteral};`,
+    '```',
+    '',
+    '## CRUD Examples',
+    '',
+    '### List Entities',
+    '```ts',
+    `const entities = await ${entityVarName}.getList({ $limit: 20, $sort: '-created' });`,
+    '```',
+    '',
+    '### Fetch a Single Entity',
+    '```ts',
+    `const entity = await ${entityVarName}.getEntity('replace-with-entity-id');`,
+    '```',
+    '',
+    '### Create an Entity',
+    '```ts',
+    `const created = await ${entityVarName}.create(${exampleLiteral});`,
+    '```',
+    '',
+    '### Update an Entity',
+    '```ts',
+    `const updated = await ${entityVarName}.update('replace-with-entity-id', {\n  ...${exampleLiteral.replace(/\n/g, '\n  ')},\n});`,
+    '```',
+    '',
+    '### Delete an Entity',
+    '```ts',
+    `await ${entityVarName}.remove('replace-with-entity-id');`,
+    '```',
+  ].join('\n');
+}
+
+function buildInterfaceDefinition(interfaceName, blueprint) {
+  const lines = [`export interface ${interfaceName} {`];
+  for (const [key, descriptor] of Object.entries(blueprint.properties)) {
+    const tsType = mapBlueprintPropertyToTs(descriptor);
+    const optionalFlag = descriptor.required ? '' : '?';
+    const description = descriptor.title || key;
+    lines.push(`  ${key}${optionalFlag}: ${tsType}; // ${description}`);
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function mapBlueprintPropertyToTs(descriptor) {
+  const baseType = descriptor.type;
+  let tsType;
+  switch (baseType) {
+    case 'number':
+      tsType = 'number';
+      break;
+    case 'boolean':
+      tsType = 'boolean';
+      break;
+    case 'date':
+    case 'datetime':
+    case 'time':
+    case 'file':
+    case 'string':
+      tsType = 'string';
+      break;
+    case 'object':
+      tsType = 'Record<string, any>';
+      break;
+    default:
+      tsType = 'any';
+  }
+
+  if (descriptor.multi) {
+    return `${tsType}[]`;
+  }
+
+  return tsType;
+}
+
+function buildExampleEntity(blueprint, sampleDoc = {}) {
+  const entity = {};
+  for (const [key, descriptor] of Object.entries(blueprint.properties)) {
+    if (sampleDoc && sampleDoc[key] !== undefined) {
+      entity[key] = sanitizeExampleValue(sampleDoc[key], descriptor);
+    } else {
+      entity[key] = getDefaultValueForDescriptor(descriptor, key);
+    }
+  }
+  return entity;
+}
+
+function sanitizeExampleValue(value, descriptor) {
+  if (Array.isArray(value)) {
+    const normalizedItems = value
+      .filter((item) => item !== null && item !== undefined)
+      .map((item) => sanitizeExampleValue(item, { ...descriptor, multi: false }));
+    return descriptor.multi ? normalizedItems : normalizedItems[0];
+  }
+
+  if (value && typeof value === 'object') {
+    if (value._bsontype) {
+      return getDefaultValueForDescriptor(descriptor);
+    }
+    const result = {};
+    for (const [innerKey, innerValue] of Object.entries(value)) {
+      result[innerKey] = sanitizeExampleValue(innerValue, { type: detectBlueprintType(innerValue) });
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function getDefaultValueForDescriptor(descriptor, key = '') {
+  const baseValue = (() => {
+    switch (descriptor.type) {
+      case 'number':
+        return 0;
+      case 'boolean':
+        return false;
+      case 'datetime':
+      case 'date':
+      case 'time':
+        return new Date().toISOString();
+      case 'object':
+        return {};
+      case 'file':
+        return 'https://example.com/file';
+      default:
+        return `Sample ${formatTitle(key || 'value')}`;
+    }
+  })();
+
+  if (descriptor.multi) {
+    return [baseValue];
+  }
+
+  return baseValue;
+}
+
+function stringifyObjectLiteral(value, level = 0) {
+  const indent = ' '.repeat(level + 2);
+  const baseIndent = ' '.repeat(level);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return '[]';
+    }
+    const items = value
+      .map((item) => `${indent}${stringifyObjectLiteral(item, level + 2)}`)
+      .join(',\n');
+    return `[\n${items}\n${baseIndent}]`;
+  }
+
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+      return '{}';
+    }
+    const lines = entries.map(
+      ([key, val]) => `${indent}${key}: ${stringifyObjectLiteral(val, level + 2)},`
+    );
+    return `\n${indent ? baseIndent : ''}{\n${lines.join('\n')}\n${baseIndent}}`;
+  }
+
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+function toCamelCase(value) {
+  return (value || '')
+    .replace(/[-_\s]+(.)?/g, (_, chr) => (chr ? chr.toUpperCase() : ''))
+    .replace(/^(.)/, (match) => match.toLowerCase());
+}

package/services/blueprint-shared.mjs

@@ -0,0 +1,77 @@
+export function formatTitle(value) {
+  return (value || '')
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+export function toIdentifier(collectionName) {
+  const sanitized = (collectionName || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+
+  return sanitized || `collection_${Date.now()}`;
+}
+
+export function ensureSingular(value = '') {
+  const normalized = value.trim();
+  const lower = normalized.toLowerCase();
+
+  if (lower.endsWith('ies')) {
+    return normalized.slice(0, -3) + normalized.slice(-3).replace(/ies$/i, 'y');
+  }
+
+  if (/(sses|xes|zes|ches|shes)$/i.test(lower)) {
+    return normalized.slice(0, -2);
+  }
+
+  if (lower.endsWith('s') && !lower.endsWith('ss')) {
+    return normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+export function detectBlueprintType(value) {
+  if (value === null || value === undefined) {
+    return 'string';
+  }
+
+  if (value instanceof Date) {
+    return 'datetime';
+  }
+
+  if (typeof value === 'number') {
+    return 'number';
+  }
+
+  if (typeof value === 'boolean') {
+    return 'boolean';
+  }
+
+  if (typeof value === 'object') {
+    if (value?._bsontype === 'ObjectId') {
+      return 'string';
+    }
+    return 'object';
+  }
+
+  return 'string';
+}
+
+export function mapBlueprintTypeToJsonSchema(type) {
+  switch (type) {
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'object':
+      return 'object';
+    default:
+      return 'string';
+  }
+}

package/services/blueprints.mjs

@@ -7,12 +7,18 @@ import { logger } from './logger.mjs';
  * @param {Object} sdk - Initialized SDK instance
  * @param {string} path - Path to blueprints directory
  */
-export async function pushBlueprints(sdk, path) {
-  const files = fs.readdirSync(path);
+export async function pushBlueprints(sdk, path, options = {}) {
+  const { targetFile } = options;
+  const directoryFiles = fs.readdirSync(path);
+  const files = targetFile ? [targetFile] : directoryFiles;
   const blueprintFiles = files.filter(f => f.endsWith('.blueprint.json'));
   
   if (blueprintFiles.length === 0) {
-    logger.warning(`No blueprint files (*.blueprint.json) found in ${path}`);
+    if (targetFile) {
+      logger.warning(`File ${targetFile} is not a .blueprint.json file. Skipping.`);
+    } else {
+      logger.warning(`No blueprint files (*.blueprint.json) found in ${path}`);
+    }
     return;
   }
   

package/services/components.mjs

@@ -7,12 +7,18 @@ import { logger } from './logger.mjs';
  * @param {Object} sdk - Initialized SDK instance
  * @param {string} path - Path to components directory
  */
-export async function pushComponents(sdk, path) {
-  const files = fs.readdirSync(path);
+export async function pushComponents(sdk, path, options = {}) {
+  const { targetFile } = options;
+  const directoryFiles = fs.readdirSync(path);
+  const files = targetFile ? [targetFile] : directoryFiles;
   const vueFiles = files.filter(f => f.endsWith('.vue'));
   
   if (vueFiles.length === 0) {
-    logger.warning(`No .vue files found in ${path}`);
+    if (targetFile) {
+      logger.warning(`File ${targetFile} is not a .vue component. Skipping.`);
+    } else {
+      logger.warning(`No .vue files found in ${path}`);
+    }
     return;
   }
   
@@ -30,7 +36,7 @@ export async function pushComponents(sdk, path) {
   
   const existingComponents = await sdk.components.getList();
   
-  await Promise.all(files.map(async (file) => {
+  await Promise.all(vueFiles.map(async (file) => {
     if (file.endsWith('.vue')) {
       const componentName = file.replace('.vue', '');
       const info = componentsJson[componentName] || {};

package/services/configurations.mjs

@@ -8,12 +8,18 @@ import { appUrl } from './sdk.mjs';
  * @param {Object} sdk - Initialized SDK instance
  * @param {string} path - Path to configurations directory
  */
-export async function pushConfigurations(sdk, path) {
-  const files = fs.readdirSync(path);
+export async function pushConfigurations(sdk, path, options = {}) {
+  const { targetFile } = options;
+  const directoryFiles = fs.readdirSync(path);
+  const files = targetFile ? [targetFile] : directoryFiles;
   const configFiles = files.filter(f => f.endsWith('.config.json'));
   
   if (configFiles.length === 0) {
-    logger.warning(`No configuration files (*.config.json) found in ${path}`);
+    if (targetFile) {
+      logger.warning(`File ${targetFile} is not a .config.json file. Skipping.`);
+    } else {
+      logger.warning(`No configuration files (*.config.json) found in ${path}`);
+    }
     return;
   }
   

package/services/plugins.mjs

@@ -9,12 +9,18 @@ import { extractMicroFrontendStructures, resolveMicroFrontendStructures } from '
  * @param {Object} sdk - Initialized SDK instance
  * @param {string} path - Path to plugins directory
  */
-export async function pushPlugins(sdk, path) {
-  const files = fs.readdirSync(path);
+export async function pushPlugins(sdk, path, options = {}) {
+  const { targetFile } = options;
+  const directoryFiles = fs.readdirSync(path);
+  const files = targetFile ? [targetFile] : directoryFiles;
   const pluginFiles = files.filter(f => f.endsWith('.plugin.json'));
   
   if (pluginFiles.length === 0) {
-    logger.warning(`No plugin files (*.plugin.json) found in ${path}`);
+    if (targetFile) {
+      logger.warning(`File ${targetFile} is not a .plugin.json file. Skipping.`);
+    } else {
+      logger.warning(`No plugin files (*.plugin.json) found in ${path}`);
+    }
     return;
   }