sfcc-metadata-cli 0.0.1 → 1.0.0

package/README.md

@@ -0,0 +1,249 @@
+# sfcc-metadata-cli
+
+A companion CLI tool to [b2c-tools](https://github.com/SalesforceCommerceCloud/b2c-tools) for creating SFCC B2C migrations.
+
+## Features
+
+- **Create migrations** with timestamp-based naming for unique, sortable names
+- **Generate custom object definitions** with interactive prompts
+- **Add site preferences** with automatic group detection
+- **Extend system objects** with custom attributes
+
+## Installation
+
+```bash
+npm install sfcc-metadata-cli --save-dev
+```
+
+## Usage
+
+```bash
+# Using npx
+npx sfcc-metadata <command>
+
+# Or add scripts to your package.json
+```
+
+### package.json Scripts (Recommended)
+
+Add these scripts to your project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "migration:create": "sfcc-metadata create",
+    "migration:custom-object": "sfcc-metadata custom-object",
+    "migration:site-preference": "sfcc-metadata site-preference",
+    "migration:system-object": "sfcc-metadata system-object"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run migration:create
+npm run migration:custom-object
+npm run migration:site-preference
+npm run migration:system-object
+```
+
+### Commands
+
+#### Create Migration
+
+Creates a new migration folder with timestamp-based naming: `YYYYMMDD_HHMMSS_description`
+
+```bash
+# Interactive mode
+npx sfcc-metadata create
+
+# With description
+npx sfcc-metadata create "add order status field"
+# Creates: 20251231_143052_add_order_status_field
+
+# Short format (date + sequence)
+npx sfcc-metadata create --short "fix shipping"
+# Creates: 20251231_01_fix_shipping
+```
+
+#### Custom Object Definition
+
+Creates a custom object type definition in the `meta/custom-objecttype-definitions.xml` file.
+
+```bash
+# Interactive mode
+npx sfcc-metadata custom-object
+
+# Example: Create a custom object for caching
+npx sfcc-metadata custom-object \
+  --type-id CacheConfig \
+  --display-name "Cache Configuration" \
+  --key-id cacheKey \
+  --storage-scope site
+```
+
+#### Site Preference
+
+Creates a site preference attribute in the `meta/system-objecttype-extensions.xml` file.
+
+```bash
+# Interactive mode
+npx sfcc-metadata site-preference
+
+# Example: Add a boolean preference
+npx sfcc-metadata site-preference \
+  --attribute-id enableFeatureX \
+  --type boolean \
+  --default-value false \
+  --group "Custom Configs"
+```
+
+#### System Object Extension
+
+Extends system objects (Order, Product, Customer, etc.) with custom attributes.
+
+```bash
+# Interactive mode
+npx sfcc-metadata system-object
+
+# Example: Add a custom attribute to Order
+npx sfcc-metadata system-object \
+  --object-type Order \
+  --attribute-id customField \
+  --type string \
+  --group Order_Custom
+```
+
+### Common Options
+
+| Option             | Alias | Description                                            |
+| ------------------ | ----- | ------------------------------------------------------ |
+| `--migrations-dir` | `-m`  | Path to migrations directory (default: `./migrations`) |
+| `--interactive`    | `-i`  | Enable/disable interactive mode                        |
+| `--help`           | `-h`  | Show help                                              |
+
+## Migration Naming Convention
+
+### New Format (Recommended)
+
+Migrations use **timestamp-based naming** for guaranteed uniqueness and natural sorting:
+
+| Format                 | Example                            | Description                 |
+| ---------------------- | ---------------------------------- | --------------------------- |
+| `YYYYMMDD_HHMMSS`      | `20251231_143052`                  | Full timestamp              |
+| `YYYYMMDD_HHMMSS_desc` | `20251231_143052_add_order_fields` | With description            |
+| `YYYYMMDD_NN_desc`     | `20251231_01_fix_shipping`         | Short format (--short flag) |
+
+**Benefits:**
+- ✅ No conflicts - timestamp ensures uniqueness
+- ✅ Self-documenting - description in the name
+- ✅ Natural sorting - alphabetical order = chronological order
+- ✅ Unlimited migrations per day
+
+### Legacy Format
+
+Old migrations using `YY.MM.N` format are still supported and will sort before new migrations.
+
+## Supported Attribute Types
+
+| Type             | Description                  |
+| ---------------- | ---------------------------- |
+| `string`         | Single-line text             |
+| `text`           | Multi-line text              |
+| `html`           | HTML content                 |
+| `int`            | Integer number               |
+| `double`         | Decimal number               |
+| `boolean`        | True/False                   |
+| `date`           | Date only                    |
+| `datetime`       | Date and time                |
+| `enum-of-string` | Single/multi-select dropdown |
+| `enum-of-int`    | Integer enumeration          |
+| `set-of-string`  | Set of strings               |
+| `image`          | Image reference              |
+| `password`       | Encrypted password           |
+
+## Examples
+
+### Create a Complete Migration
+
+```bash
+# 1. Create the migration folder
+node tools/migration-helper/index.js create
+
+# 2. Add a custom object
+node tools/migration-helper/index.js custom-object
+
+# 3. Add a site preference
+node tools/migration-helper/index.js site-preference
+
+# 4. Preview the migration
+npm run migrate
+
+# 5. Apply the migration
+npm run migrate:apply
+```
+
+### Generated XML Examples
+
+#### Custom Object
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <custom-type type-id="MyCustomObject">
+        <display-name xml:lang="x-default">My Custom Object</display-name>
+        <staging-mode>source-to-target</staging-mode>
+        <storage-scope>site</storage-scope>
+        <key-definition attribute-id="key">
+            <type>string</type>
+            <min-length>0</min-length>
+        </key-definition>
+        <attribute-definitions>
+            <!-- attributes -->
+        </attribute-definitions>
+        <group-definitions>
+            <!-- groups -->
+        </group-definitions>
+    </custom-type>
+</metadata>
+```
+
+#### Site Preference
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="SitePreferences">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="myPreference">
+                <display-name xml:lang="x-default">My Preference</display-name>
+                <type>boolean</type>
+                <mandatory-flag>false</mandatory-flag>
+                <externally-managed-flag>false</externally-managed-flag>
+                <default-value>false</default-value>
+            </attribute-definition>
+        </custom-attribute-definitions>
+        <group-definitions>
+            <attribute-group group-id="Custom Configs">
+                <!-- existing attributes -->
+                <attribute attribute-id="myPreference"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+## Integration with b2c-tools
+
+After creating migrations with this tool, use b2c-tools to apply them:
+
+```bash
+# Preview migrations
+node build/b2c-tools.js import migrate --dry-run
+
+# Apply migrations
+node build/b2c-tools.js import migrate
+```
+
+## License
+
+AGPL-3.0-or-later

package/biome.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+    "organizeImports": {
+        "enabled": true
+    },
+    "linter": {
+        "enabled": true,
+        "rules": {
+            "recommended": true,
+            "complexity": {
+                "noForEach": "off"
+            },
+            "style": {
+                "noNonNullAssertion": "off"
+            }
+        }
+    },
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4
+    },
+    "javascript": {
+        "formatter": {
+            "quoteStyle": "single",
+            "semicolons": "always"
+        }
+    },
+    "files": {
+        "ignore": ["node_modules", "package-lock.json"]
+    }
+}

package/commands/create-migration.js

@@ -0,0 +1,157 @@
+/**
+ * Create Migration Command
+ * Creates a new migration folder with timestamp-based naming convention
+ * Format: YYYYMMDD_HHMMSS or YYYYMMDD_HHMMSS_description
+ */
+
+const path = require('node:path');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const {
+    generateMigrationName,
+    generateShortMigrationName,
+    listMigrations,
+    ensureDir,
+    getLatestMigration,
+} = require('../lib/utils');
+
+module.exports = {
+    command: 'create [description]',
+    aliases: ['new', 'init'],
+    desc: 'Create a new migration folder (format: YYYYMMDD_HHMMSS_description)',
+    builder: (yargs) => {
+        return yargs
+            .positional('description', {
+                describe:
+                    'Short description for the migration (e.g., "add_order_fields")',
+                type: 'string',
+            })
+            .option('short', {
+                alias: 's',
+                type: 'boolean',
+                default: false,
+                description:
+                    'Use short format: YYYYMMDD_NN instead of timestamp',
+            })
+            .option('with-meta', {
+                type: 'boolean',
+                default: false,
+                description: 'Create meta folder structure',
+            })
+            .option('interactive', {
+                alias: 'i',
+                type: 'boolean',
+                default: false,
+                description: 'Interactive mode with prompts',
+            });
+    },
+    handler: async (argv) => {
+        const migrationsDir = path.resolve(argv.migrationsDir);
+
+        try {
+            let description = argv.description;
+            const withMeta = argv.withMeta;
+            const useShortFormat = argv.short;
+
+            // List existing migrations
+            const existingMigrations = listMigrations(migrationsDir);
+            const latestMigration = getLatestMigration(migrationsDir);
+
+            if (existingMigrations.length > 0) {
+                console.log(chalk.cyan('\nRecent migrations:'));
+                existingMigrations.slice(-5).forEach((m) => {
+                    console.log(chalk.gray(`  - ${m}`));
+                });
+                if (existingMigrations.length > 5) {
+                    console.log(
+                        chalk.gray(
+                            `  ... and ${existingMigrations.length - 5} more`,
+                        ),
+                    );
+                }
+                console.log();
+            }
+
+            if (argv.interactive || (!description && process.stdin.isTTY)) {
+                const answers = await inquirer.prompt([
+                    {
+                        type: 'input',
+                        name: 'description',
+                        message:
+                            'Migration description (e.g., "add_order_status_field"):',
+                        filter: (input) => input.trim(),
+                        transformer: (input) => {
+                            // Show preview of the sanitized name
+                            const sanitized = input
+                                .toLowerCase()
+                                .replace(/\s+/g, '_')
+                                .replace(/[^a-z0-9_]/g, '');
+                            return (
+                                input +
+                                (sanitized !== input
+                                    ? chalk.gray(` → ${sanitized}`)
+                                    : '')
+                            );
+                        },
+                    },
+                ]);
+
+                description = answers.description || description;
+            }
+
+            // Generate migration name
+            const migrationName = useShortFormat
+                ? generateShortMigrationName(migrationsDir, description)
+                : generateMigrationName(migrationsDir, description);
+
+            // Check if migration already exists
+            const migrationPath = path.join(migrationsDir, migrationName);
+            if (existingMigrations.includes(migrationName)) {
+                console.error(
+                    chalk.red(
+                        `\nError: Migration "${migrationName}" already exists`,
+                    ),
+                );
+                process.exit(1);
+            }
+
+            // Create migration folder
+            ensureDir(migrationPath);
+            console.log(chalk.green(`\n✓ Created migration: ${migrationName}`));
+
+            // Create meta folder if requested
+            if (withMeta) {
+                const metaPath = path.join(migrationPath, 'meta');
+                ensureDir(metaPath);
+                console.log(chalk.green('✓ Created meta folder'));
+            }
+
+            console.log(chalk.cyan(`\nMigration path: ${migrationPath}`));
+            console.log(chalk.gray('\nNext steps:'));
+            console.log(
+                chalk.gray('  - Add XML files to the migration folder'),
+            );
+            console.log(
+                chalk.gray(
+                    '  - Use "migration-helper custom-object" to add custom object definitions',
+                ),
+            );
+            console.log(
+                chalk.gray(
+                    '  - Use "migration-helper site-preference" to add site preferences',
+                ),
+            );
+            console.log(
+                chalk.gray('  - Run "npm run migrate" to preview migrations'),
+            );
+            console.log(
+                chalk.gray(
+                    '  - Run "npm run migrate:apply" to apply migrations',
+                ),
+            );
+        } catch (error) {
+            console.error(chalk.red(`\nError: ${error.message}`));
+            process.exit(1);
+        }
+    },
+};