mcdev 9.0.2 → 10.0.0

package/scripts/verify-progress-fixture.mjs

@@ -0,0 +1,362 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, rm, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+    getSpinnerScenarios,
+    normalizeSpinnerOutput,
+} from '../test/helpers/progress-scenarios.js';
+
+const repository = path.resolve(import.meta.dirname, '..');
+const fixturePath = path.join(repository, 'test', 'fixtures', 'progress-visual.json');
+const npmCli = process.env.npm_execpath;
+const dependencies = {
+    'cli-progress': '3.12.0',
+    'yocto-spinner': '1.2.2',
+};
+assert.ok(npmCli, 'Run this verifier through npm run verify:progress-fixture');
+
+const runRoot = await mkdtemp(path.join(os.tmpdir(), 'mcdev-progress-provenance-'));
+const ownershipToken = randomUUID();
+const ownershipMarker = path.join(runRoot, `.owner-${ownershipToken}`);
+const installRoot = path.join(runRoot, 'dependencies');
+const registeredTargets = new Set();
+
+/** @param {string} target run-owned path */
+function register(target) {
+    registeredTargets.add(path.resolve(target));
+}
+
+/**
+ * Validates a registered strict descendant before cleanup.
+ *
+ * @param {string} target registered descendant to validate
+ * @returns {Promise.<string>} validated absolute target
+ */
+async function validateRegisteredDescendant(target) {
+    assert.ok(target, 'Cleanup target must not be empty');
+    const resolvedRoot = path.resolve(runRoot);
+    const resolvedTarget = path.resolve(target);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    assert.notEqual(resolvedTarget, resolvedRoot, 'Cleanup target must not be the run root');
+    assert.ok(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+    assert.ok(!/[*?]/u.test(target), 'Cleanup target must not contain wildcards');
+    assert.ok(registeredTargets.has(resolvedTarget), 'Cleanup target must be registered');
+    const stats = await lstat(resolvedTarget);
+    assert.equal(stats.isSymbolicLink(), false, 'Cleanup target must not be a symlink or junction');
+    return resolvedTarget;
+}
+
+/** @param {string} target registered directory to remove recursively */
+async function removeRegisteredDirectory(target) {
+    const validated = await validateRegisteredDescendant(target);
+    await rm(validated, { recursive: true, force: false });
+    registeredTargets.delete(validated);
+}
+
+/** @param {string} target registered file to remove */
+async function removeRegisteredFile(target) {
+    const validated = await validateRegisteredDescendant(target);
+    await unlink(validated);
+    registeredTargets.delete(validated);
+}
+
+/**
+ * Runs npm in the isolated run directory.
+ *
+ * @param {string[]} arguments_ npm arguments
+ * @returns {void}
+ */
+function runNpm(arguments_) {
+    const result = spawnSync(process.execPath, [npmCli, ...arguments_], {
+        cwd: installRoot,
+        encoding: 'utf8',
+        timeout: 180_000,
+    });
+    assert.ifError(result.error);
+    assert.equal(
+        result.status,
+        0,
+        [result.stderr, result.stdout].filter(Boolean).join('\n') || 'npm install failed'
+    );
+}
+
+/**
+ * Creates a deterministic terminal stream and records every emitted byte.
+ *
+ * @param {object} options stream characteristics
+ * @param {boolean} options.isTTY terminal status
+ * @param {number} options.columns terminal width
+ * @param {boolean} [options.hasColors] color support
+ * @returns {{stream: object, output: () => string}} fake stream and captured output
+ */
+function createStream({ isTTY, columns, hasColors = true }) {
+    const chunks = [];
+    const stream = {
+        isTTY,
+        columns,
+        hasColors: () => hasColors,
+        write: (chunk, encoding, callback) => {
+            chunks.push(Buffer.from(String(chunk)));
+            if (typeof encoding === 'function') {
+                encoding();
+            }
+            if (typeof callback === 'function') {
+                callback();
+            }
+            return true;
+        },
+        cursorTo: (x) => {
+            chunks.push(Buffer.from(`\u001B[${x + 1}G`));
+        },
+        moveCursor: (x, y) => {
+            if (x) {
+                chunks.push(Buffer.from(`\u001B[${Math.abs(x)}${x < 0 ? 'D' : 'C'}`));
+            }
+            if (y) {
+                chunks.push(Buffer.from(`\u001B[${Math.abs(y)}${y < 0 ? 'A' : 'B'}`));
+            }
+        },
+        clearLine: (direction) => {
+            chunks.push(Buffer.from(direction === 1 ? '\u001B[0K' : '\u001B[2K'));
+        },
+    };
+    return { stream, output: () => Buffer.concat(chunks).toString('base64') };
+}
+
+/** @returns {{advance: (milliseconds: number) => void, runIntervals: () => void, restore: () => void, active: () => number}} deterministic clock controls */
+function installClock() {
+    const originals = { now: Date.now, setTimeout, clearTimeout, setInterval, clearInterval };
+    let now = 1_000;
+    let nextId = 1;
+    const timeouts = new Map();
+    const intervals = new Map();
+    Object.defineProperty(Date, 'now', { configurable: true, value: () => now });
+    Object.defineProperties(globalThis, {
+        setTimeout: {
+            configurable: true,
+            value: (callback, delay) => {
+                const id = nextId++;
+                timeouts.set(id, { callback, delay });
+                return id;
+            },
+        },
+        clearTimeout: { configurable: true, value: (id) => timeouts.delete(id) },
+        setInterval: {
+            configurable: true,
+            value: (callback, delay) => {
+                const id = nextId++;
+                intervals.set(id, { callback, delay });
+                return id;
+            },
+        },
+        clearInterval: { configurable: true, value: (id) => intervals.delete(id) },
+    });
+    return {
+        advance: (milliseconds) => {
+            now += milliseconds;
+        },
+        runIntervals: () => {
+            for (const { callback } of intervals.values()) {
+                callback();
+            }
+        },
+        active: () => timeouts.size + intervals.size,
+        restore: () => {
+            Object.defineProperty(Date, 'now', { configurable: true, value: originals.now });
+            Object.defineProperties(globalThis, {
+                setTimeout: { configurable: true, value: originals.setTimeout },
+                clearTimeout: { configurable: true, value: originals.clearTimeout },
+                setInterval: { configurable: true, value: originals.setInterval },
+                clearInterval: { configurable: true, value: originals.clearInterval },
+            });
+        },
+    };
+}
+
+/**
+ * Captures the complete committed oracle from the exact dependencies.
+ *
+ * @param {typeof import('cli-progress')} cliProgress exact progress dependency
+ * @param {(options: object) => object} createSpinner exact spinner factory
+ * @returns {object} captured scenarios and cleanup metadata
+ */
+function createCaptures(cliProgress, createSpinner) {
+    /**
+     * Captures one progress bar lifecycle.
+     *
+     * @param {string} format configured bar template
+     * @returns {{output: string, activeTimers: number}} captured output
+     */
+    function captureBar(format) {
+        const clock = installClock();
+        const capture = createStream({ isTTY: true, columns: 120 });
+        try {
+            const bar = new cliProgress.SingleBar(
+                { format, stream: capture.stream },
+                cliProgress.Presets.shades_classic
+            );
+            bar.start(4, 0);
+            clock.advance(250);
+            bar.update(1);
+            clock.advance(250);
+            bar.update(2);
+            clock.advance(250);
+            bar.update(4);
+            bar.stop();
+            return { output: capture.output(), activeTimers: clock.active() };
+        } finally {
+            clock.restore();
+        }
+    }
+
+    /**
+     * Captures one spinner lifecycle.
+     *
+     * @param {object} [options] scenario controls
+     * @returns {{output: string, activeTimers: number, writeRestored: boolean}} captured output
+     */
+    function captureSpinner(options = {}) {
+        const clock = installClock();
+        const capture = createStream({
+            isTTY: options.tty ?? true,
+            columns: options.columns ?? 16,
+            hasColors: true,
+        });
+        const originalWrite = capture.stream.write;
+        try {
+            const spinner = createSpinner({
+                text: 'Publishing multi-step journey…',
+                stream: capture.stream,
+                spinner: options.spinner,
+                handleSignals: false,
+                color: options.color,
+            });
+            spinner.start();
+            clock.advance(80);
+            clock.runIntervals();
+            if (options.partial) {
+                capture.stream.write('partial');
+                clock.advance(80);
+                clock.runIntervals();
+                capture.stream.write(' complete\n');
+            } else {
+                capture.stream.write('status update\n');
+            }
+            clock.advance(80);
+            clock.runIntervals();
+            if (options.finish === 'success') {
+                spinner.success('Done');
+            } else if (options.finish === 'error') {
+                spinner.error('Failed');
+            } else {
+                spinner.stop();
+            }
+            return {
+                output: Buffer.from(
+                    normalizeSpinnerOutput(Buffer.from(capture.output(), 'base64').toString()),
+                    'utf8'
+                ).toString('base64'),
+                activeTimers: clock.active(),
+                writeRestored: capture.stream.write === originalWrite,
+            };
+        } finally {
+            clock.restore();
+        }
+    }
+
+    return {
+        assetDownload: captureBar(
+            '                 Downloading [{bar}] {percentage}% | {value}/{total} | asset-email'
+        ),
+        devopsChanges: captureBar(
+            '                 Processing changes [{bar}] {percentage}% | {value}/{total}'
+        ),
+        assetMigration: captureBar(
+            '                 Migrating asset-message [{bar}] {percentage}% | {value}/{total}'
+        ),
+        ...Object.fromEntries(
+            Object.entries(getSpinnerScenarios()).map(([name, options]) => [
+                name,
+                captureSpinner(options),
+            ])
+        ),
+    };
+}
+
+const originalCi = process.env.CI;
+const originalForceColor = process.env.FORCE_COLOR;
+const originalTerm = process.env.TERM;
+try {
+    register(ownershipMarker);
+    await writeFile(ownershipMarker, ownershipToken, { flag: 'wx' });
+    register(installRoot);
+    await mkdir(installRoot);
+    await writeFile(
+        path.join(installRoot, 'package.json'),
+        `${JSON.stringify({ private: true, type: 'module' }, null, 2)}\n`
+    );
+    runNpm([
+        'install',
+        '--ignore-scripts',
+        '--no-audit',
+        '--no-fund',
+        '--package-lock=false',
+        '--workspaces=false',
+        ...Object.entries(dependencies).map(([name, version]) => `${name}@${version}`),
+    ]);
+
+    process.env.FORCE_COLOR = '1';
+    const require = createRequire(path.join(installRoot, 'package.json'));
+    for (const [name, version] of Object.entries(dependencies)) {
+        const installed = JSON.parse(
+            await readFile(path.join(installRoot, 'node_modules', name, 'package.json'), 'utf8')
+        );
+        assert.equal(installed.name, name);
+        assert.equal(installed.version, version);
+    }
+    const cliProgress = require('cli-progress');
+    const spinnerModule = await import(
+        pathToFileURL(path.join(installRoot, 'node_modules', 'yocto-spinner', 'index.js')).href
+    );
+
+    delete process.env.CI;
+    process.env.TERM = 'xterm-256color';
+    const expected = JSON.parse(await readFile(fixturePath, 'utf8'));
+    const actual = createCaptures(cliProgress, spinnerModule.default);
+    assert.deepEqual(Object.keys(actual), Object.keys(expected), 'Fixture scenario set differs');
+    assert.deepEqual(actual, expected, 'Exact dependency output differs from committed fixture');
+    process.stdout.write(
+        `Verified ${path.relative(repository, fixturePath)} from cli-progress@${dependencies['cli-progress']} and yocto-spinner@${dependencies['yocto-spinner']}.\n`
+    );
+} finally {
+    if (originalCi === undefined) {
+        delete process.env.CI;
+    } else {
+        process.env.CI = originalCi;
+    }
+    if (originalForceColor === undefined) {
+        delete process.env.FORCE_COLOR;
+    } else {
+        process.env.FORCE_COLOR = originalForceColor;
+    }
+    if (originalTerm === undefined) {
+        delete process.env.TERM;
+    } else {
+        process.env.TERM = originalTerm;
+    }
+    let markerContents;
+    try {
+        markerContents = await readFile(ownershipMarker, 'utf8');
+    } catch {
+        markerContents = undefined;
+    }
+    assert.equal(markerContents, ownershipToken, 'Run ownership marker changed or disappeared');
+    await removeRegisteredDirectory(installRoot);
+    await removeRegisteredFile(ownershipMarker);
+    await rmdir(runRoot);
+}

package/types/init-declarations.type-test.js

@@ -0,0 +1,10 @@
+import InitConfig from '../@types/lib/util/init.config.js';
+import InitNpm from '../@types/lib/util/init.npm.js';
+
+const properties = /** @type {import('./mcdev.d.js').Mcdevrc} */ ({});
+
+/** @type {Promise.<boolean>} */
+export const fixMcdevConfigResult = InitConfig.fixMcdevConfig(properties, '10.0.0');
+
+/** @type {Promise.<boolean>} */
+export const installDependenciesResult = InitNpm.installDependencies('repository', '10.0.0');

package/types/mcdev.d.js

@@ -10,13 +10,20 @@
  */
 
 /**
- * @typedef {Object.<string, string>} TemplateMap
- * @typedef {'asset'|'asset-archive'|'asset-asset'|'asset-audio'|'asset-block'|'asset-code'|'asset-document'|'asset-image'|'asset-message'|'asset-other'|'asset-rawimage'|'asset-template'|'asset-textfile'|'asset-video'|'attributeGroup'|'attributeSet'|'automation'|'campaign'|'contentArea'|'dataExtension'|'dataExtensionField'|'dataExtensionTemplate'|'dataExtract'|'dataExtractType'|'discovery'|'deliveryProfile'|'email'|'emailSend'|'event'|'fileLocation'|'fileTransfer'|'filter'|'folder'|'importFile'|'journey'|'list'|'mobileCode'|'mobileKeyword'|'mobileMessage'|'query'|'role'|'script'|'sendClassification'|'senderProfile'|'transactionalEmail'|'transactionalPush'|'transactionalSMS'|'triggeredSend'|'user'|'verification'} SupportedMetadataTypes
+ * @typedef {object} RegexTemplateValue
+ * @property {string} search regular expression source, compiled with the global flag
+ * @property {string | number | boolean} replace literal build value rendered in text or JSON string fields
+ * @property {string} [template] native JavaScript replacement expression; defaults to the market key in triple braces
+ */
+
+/**
+ * @typedef {Object.<string, string | number | boolean | RegexTemplateValue>} TemplateMap
+ * @typedef {'asset'|'asset-archive'|'asset-asset'|'asset-audio'|'asset-block'|'asset-code'|'asset-document'|'asset-image'|'asset-email'|'asset-mobile'|'asset-other'|'asset-webstudio'|'asset-rawimage'|'asset-template'|'asset-textfile'|'asset-video'|'attributeGroup'|'attributeSet'|'automation'|'campaign'|'contentArea'|'dataExtension'|'dataExtensionField'|'dataExtensionTemplate'|'dataExtract'|'dataExtractType'|'discovery'|'deliveryProfile'|'email'|'emailSend'|'event'|'fileLocation'|'fileTransfer'|'filter'|'folder'|'importFile'|'journey'|'list'|'mobileCode'|'mobileKeyword'|'mobileMessage'|'query'|'role'|'script'|'sendClassification'|'senderProfile'|'transactionalEmail'|'transactionalPush'|'transactionalSMS'|'triggeredSend'|'user'|'verification'} SupportedMetadataTypes
  * @typedef {Object.<string, string[] | null>} TypeKeyCombo object-key=SupportedMetadataTypes, value=array of external keys
  */
 
 /**
- * @typedef {Object.<any, any>} MetadataTypeItem generic metadata item
+ * @typedef {ReturnType<JSON['parse']>} MetadataTypeItem generic JSON metadata item
  * @typedef {Object.<string, MetadataTypeItem>} MetadataTypeMap key=customer key
  * @typedef {Object.<string, MetadataTypeMap>} MultiMetadataTypeMap key=Supported MetadataType
  * @typedef {Object.<string, MetadataTypeItem[]>} MultiMetadataTypeList key=Supported MetadataType
@@ -77,9 +84,9 @@
  */
 
 /**
- * @typedef {Object.<string, any>} AssetItem
+ * @typedef {ReturnType<JSON['parse']>} AssetItem
  * @typedef {Object.<string, AssetItem>} AssetMap
- * @typedef {'archive'|'asset'|'audio'|'block'|'code'|'document'|'image'|'message'|'other'|'rawimage'|'template'|'textfile'|'video'} AssetSubType
+ * @typedef {'archive'|'asset'|'audio'|'block'|'code'|'document'|'email'|'image'|'mobile'|'other'|'rawimage'|'template'|'textfile'|'video'|'webstudio'} AssetSubType
  */
 
 /**
@@ -250,8 +257,8 @@
  * @property {number} [timezoneId] see this.definition.timeZoneMapping
  * @property {number} [timeZoneId] same as timezoneId but returned by legacy-API; see this.definition.timeZoneMapping
  * @property {number} [rangeTypeId] ?
- * @property {any} [pattern] ?
- * @property {any} [scheduledTime] ?
+ * @property {object|string|null} [pattern] schedule pattern returned by the API
+ * @property {string|null} [scheduledTime] scheduled timestamp returned by the API
  * @property {string} [scheduledStatus] ?
  */
 
@@ -294,7 +301,7 @@
  * @property {string} [CustomerKey] key (SOAP API)
  * @property {string} [name] name (Rest API)
  * @property {string} [Name] name (SOAP API)
- * @property {any} [notifications] notifications
+ * @property {object[]} [notifications] notifications
  * @property {string} [description] -
  * @property {'scheduled'|'triggered'|'automationtriggered'} [type] Starting Source = Schedule / File Drop
  * @property {'scheduled'|'triggered'|'automationtriggered'} [automationType] Starting Source = Schedule / File Drop; from legacy api
@@ -362,7 +369,7 @@
  * @property {'move'|'add/update'|'delete'} gitAction what git recognized as an action
  * @property {string} _credential mcdev credential name
  * @property {string} _businessUnit mcdev business unit name inside of _credential
- * @typedef {import('simple-git').DiffResultTextFile & McdevDeltaPkgItem} DeltaPkgItem
+ * @typedef {McdevDeltaPkgItem} DeltaPkgItem
  */
 
 /**
@@ -487,7 +494,7 @@
  * @typedef {object} SoapRequestParams
  * @property {string} [continueRequest] request id
  * @property {object} [options] additional options (CallsInConversation, Client, ConversationID, Priority, RequestType, SaveOptions, ScheduledTime, SendResponseTo, SequenceCode)
- * @property {*} [clientIDs] ?
+ * @property {{ID:number}[]} [clientIDs] client identifiers
  * @property {SoapSDKFilter} [filter] simple or complex
 complex
  * @property {boolean} [QueryAllAccounts] all BUs or just one
@@ -529,7 +536,7 @@ complex
  * @typedef {object} AssetRequestParams
  * @property {string} [continueRequest] request id
  * @property {object} [options] additional options (CallsInConversation, Client, ConversationID, Priority, RequestType, SaveOptions, ScheduledTime, SendResponseTo, SequenceCode)
- * @property {*} [clientIDs] ?
+ * @property {{ID:number}[]} [clientIDs] client identifiers
 complex
  * @property {object} [page] pagination
  * @property {string[]} [fields] list of fields we want returned
@@ -600,7 +607,6 @@ complex
  * @property {boolean} supports.delete can you delete records of this type
  * @property {boolean} supports.changeKey can you change the key of existing records of this type
  * @property {boolean} supports.buildTemplate can you apply templating on downloaded records of this type
- * @property {boolean} supports.retrieveAsTemplate can you retrieve & template in one step
  */
 
 /**

package/.beautyamp.json

@@ -1,13 +0,0 @@
-{
-    "ampscript": {
-        "capitalizeAndOrNot": true,
-        "capitalizeIfFor": true,
-        "capitalizeSet": true,
-        "capitalizeVar": true,
-        "maxParametersPerLine": 4
-    },
-    "editor": {
-        "insertSpaces": true,
-        "tabSize": 4
-    }
-}

package/.bitbucket/PULL_REQUEST_TEMPLATE.md

@@ -1,19 +0,0 @@
-# PR details
-
-## What is the purpose of this pull request? (put an "X" next to an item)
-
-- [ ] Documentation update
-- [ ] Bug fix
-- [ ] New metadata support
-- [ ] Enhanced metadata
-- [ ] Add a CLI option
-- [ ] Add something to the core
-- [ ] Other, please explain:
-
-## What changes did you make? (Give an overview)
-
-...
-
-## Is there anything you'd like reviewers to focus on?
-
-...