@qelos/plugins-cli 0.0.15 → 0.0.17

package/commands/blueprints.mjs

@@ -17,6 +17,12 @@ export default function blueprintsCommand(program) {
             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

@@ -1,12 +1,11 @@
-import fs from "node:fs";
 import path from "node:path";
-import { MongoClient } from "mongodb";
 import { logger } from "../services/logger.mjs";
+import {
+  SUPPORTED_PROTOCOL,
+  generateBlueprintsFromMongo,
+} from "../services/blueprint-generator.mjs";
 
-const SUPPORTED_PROTOCOL = /^mongodb:\/\//i;
-const SAMPLE_SIZE = 50;
-
-export default async function blueprintsController({ uri, path: targetPath }) {
+export default async function blueprintsController({ uri, path: targetPath, guides = true }) {
   const connectionUri = uri || "mongodb://localhost:27017/db";
 
   if (!SUPPORTED_PROTOCOL.test(connectionUri)) {
@@ -15,322 +14,15 @@ export default async function blueprintsController({ uri, path: targetPath }) {
   }
 
   const targetDir = path.join(process.cwd(), targetPath);
-  ensureDirectory(targetDir);
-
-  const client = new MongoClient(connectionUri, {
-    serverSelectionTimeoutMS: 10_000,
-  });
+  const shouldGenerateGuides = guides !== false;
 
   try {
-    await client.connect();
-    const dbName = getDatabaseName(connectionUri);
-    const db = client.db(dbName);
-
-    logger.section(`Connected to MongoDB database: ${db.databaseName}`);
-
-    const collections = await db.listCollections().toArray();
-    const filteredCollections = collections.filter(
-      (collection) => !collection.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, collection.name, targetDir);
-    }
-
-    logger.success(
-      `Generated ${filteredCollections.length} blueprint file(s) in ${targetDir}`
-    );
-  } catch (error) {
-    logger.error("Failed to generate blueprints", error);
-    process.exit(1);
-  } finally {
-    await client.close().catch(() => {});
-  }
-}
-
-function ensureDirectory(targetDir) {
-  if (!fs.existsSync(targetDir)) {
-    fs.mkdirSync(targetDir, { recursive: true });
-    logger.info(`Created output directory at ${targetDir}`);
-  }
-}
-
-async function generateBlueprintForCollection(db, collectionName, targetDir) {
-  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 filePath = path.join(
+    await generateBlueprintsFromMongo({
+      uri: connectionUri,
       targetDir,
-      `${blueprint.identifier}.blueprint.json`
-    );
-
-    fs.writeFileSync(filePath, JSON.stringify(blueprint, null, 2));
-    logger.success(`Blueprint generated: ${filePath}`);
-  } 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 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";
-}
-
-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: ["*"],
-  }));
-}
-
-function toIdentifier(collectionName) {
-  const sanitized = collectionName
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "_")
-    .replace(/^_+|_+$/g, "");
-
-  return sanitized || `collection_${Date.now()}`;
-}
-
-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());
-}
-
-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 mapBlueprintTypeToJsonSchema(type) {
-  switch (type) {
-    case "number":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "object":
-      return "object";
-    default:
-      return "string";
-  }
-}
-
-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 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;
-}
-
-function getDatabaseName(connectionUri) {
-  try {
-    const parsed = new URL(connectionUri);
-    return parsed.pathname.replace(/^\//, "") || undefined;
+      createGuides: shouldGenerateGuides,
+    });
   } catch {
-    return undefined;
+    process.exit(1);
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/plugins-cli",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "CLI to manage QELOS plugins",
   "main": "cli.mjs",
   "bin": {
@@ -14,7 +14,7 @@
   "author": "David Meir-Levy <davidmeirlevy@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "@qelos/sdk": "^3.11.0",
+    "@qelos/sdk": "^3.11.1",
     "cli-progress": "^3.12.0",
     "cli-select": "^1.1.2",
     "decompress-zip": "^0.3.3",

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/components.mjs

@@ -41,16 +41,18 @@ export async function pushComponents(sdk, path, options = {}) {
       const componentName = file.replace('.vue', '');
       const info = componentsJson[componentName] || {};
       const content = fs.readFileSync(join(path, file), 'utf-8');
+      const targetIdentifier = info.identifier || componentName;
+      const targetDescription = info.description || 'Component description';
       
       logger.step(`Pushing component: ${componentName}`);
       
       const existingComponent = existingComponents.find(
-        component => component.identifier === componentName
+        component => component.identifier === targetIdentifier || component.componentName === componentName
       );
       
       if (existingComponent) {
         await sdk.components.update(existingComponent._id, {
-          identifier: info.identifier || existingComponent.identifier || componentName,
+          identifier: targetIdentifier,
           componentName: componentName,
           content,
           description: info.description || existingComponent.description || 'Component description'
@@ -58,10 +60,10 @@ export async function pushComponents(sdk, path, options = {}) {
         logger.success(`Updated: ${componentName}`);
       } else {
         await sdk.components.create({
-          identifier: info.identifier || componentName,
+          identifier: targetIdentifier,
           componentName: componentName,
           content,
-          description: info.description || 'Component description'
+          description: targetDescription
         });
         logger.success(`Created: ${componentName}`);
       }