dazscript-framework 1.0.29 → 1.0.31

package/dist/scripts/integration.js

@@ -0,0 +1,304 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const defaultTimeoutMs = 300000;
+
+function isDazPath(value) {
+  return /^[A-Za-z]:[\\/]/.test(String(value || ''));
+}
+
+function normalizeForDaz(value) {
+  const normalized = String(value).replace(/\\/g, '/');
+  const driveMatch = normalized.match(/\/drive_([A-Za-z])\/(.+)$/);
+  if (driveMatch) {
+    return `${driveMatch[1].toUpperCase()}:/${driveMatch[2]}`;
+  }
+
+  return normalized;
+}
+
+function unquoteEnvValue(value) {
+  const trimmed = String(value || '').trim();
+  if (trimmed.length < 2) return trimmed;
+
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if ((first === '"' && last === '"') || (first === '\'' && last === '\'')) {
+    return trimmed.substring(1, trimmed.length - 1);
+  }
+
+  return trimmed;
+}
+
+function loadEnvFile(envPath, targetEnv) {
+  if (!envPath || !fs.existsSync(envPath)) return false;
+
+  const lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line || line[0] === '#') continue;
+
+    const separatorIndex = line.indexOf('=');
+    if (separatorIndex <= 0) continue;
+
+    const key = line.substring(0, separatorIndex).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    if (targetEnv[key] !== undefined) continue;
+
+    targetEnv[key] = unquoteEnvValue(line.substring(separatorIndex + 1));
+  }
+
+  return true;
+}
+
+function assertRequiredFile(label, filePath, allowDazPath) {
+  if (!filePath) {
+    throw new Error(`missing required env: ${label}`);
+  }
+
+  if (allowDazPath && isDazPath(filePath)) {
+    return filePath;
+  }
+
+  const resolvedPath = path.resolve(filePath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`${label} does not exist: ${resolvedPath}`);
+  }
+
+  return resolvedPath;
+}
+
+function resolveIntegrationOptions(cwd, rawOptions, env) {
+  const options = rawOptions || {};
+  const projectRoot = path.resolve(cwd || process.cwd());
+  const envFile = path.resolve(projectRoot, options.envFile || '.env.integration.local');
+  const fixturePath = options.fixture
+    ? path.resolve(projectRoot, options.fixture)
+    : '';
+
+  if (!fixturePath) {
+    throw new Error('missing required option: --fixture <path>');
+  }
+  if (!fs.existsSync(fixturePath)) {
+    throw new Error(`fixture file does not exist: ${fixturePath}`);
+  }
+
+  const dazStudioExe = assertRequiredFile(
+    'DAZ_STUDIO_EXE',
+    options.dazStudio || env.DAZ_STUDIO_EXE,
+    false
+  );
+
+  const rawContentPath = options.contentDuf || env.DAZ_TEST_CONTENT_DUF || '';
+  if (options.requireContent) {
+    assertRequiredFile('DAZ_TEST_CONTENT_DUF', rawContentPath, true);
+  }
+  else if (rawContentPath && !isDazPath(rawContentPath) && !fs.existsSync(path.resolve(rawContentPath))) {
+    throw new Error(`DAZ_TEST_CONTENT_DUF does not exist: ${path.resolve(rawContentPath)}`);
+  }
+
+  const timeoutMs = Number(options.timeoutMs || env.DAZ_TEST_TIMEOUT_MS || defaultTimeoutMs);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`invalid timeout: ${options.timeoutMs || env.DAZ_TEST_TIMEOUT_MS}`);
+  }
+
+  const outDir = path.resolve(projectRoot, options.outDir || './test/integration/out');
+  const fixtureName = path.basename(fixturePath).replace(/\.dsa\.ts$/i, '').replace(/\.ts$/i, '');
+  const fixtureRoot = path.join(outDir, 'fixture');
+  const resultPath = path.join(fixtureRoot, 'result.json');
+  const frameworkRoot = path.resolve(__dirname, '..', '..');
+
+  return {
+    projectRoot,
+    frameworkRoot,
+    envFile,
+    fixturePath,
+    fixtureName,
+    outDir,
+    fixtureRoot,
+    resultPath,
+    dazStudioExe,
+    contentPath: rawContentPath ? normalizeForDaz(rawContentPath) : '',
+    requireContent: Boolean(options.requireContent),
+    timeoutMs,
+    appDataPath: options.appDataPath || 'DazScriptFramework/integration-tests',
+    bundleName: options.bundleName || 'Integration Test Fixture',
+    env,
+  };
+}
+
+function run(command, args, options) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env || process.env,
+    encoding: 'utf8',
+    stdio: options.stdio || 'inherit',
+    timeout: options.timeoutMs,
+  });
+
+  if (result.error) {
+    if (result.error.code === 'ETIMEDOUT') {
+      throw new Error(`${command} timed out after ${options.timeoutMs}ms`);
+    }
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} exited with code ${result.status}`);
+  }
+
+  return result;
+}
+
+function writeFile(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function buildFixtureProject(options) {
+  fs.rmSync(options.fixtureRoot, { recursive: true, force: true });
+  fs.mkdirSync(path.join(options.fixtureRoot, 'src'), { recursive: true });
+
+  writeFile(path.join(options.fixtureRoot, 'package.json'), JSON.stringify({
+    private: true,
+    scripts: {
+      build: 'dazscript build --out-dir ./out',
+    },
+    dependencies: {
+      'dazscript-framework': `file:${options.frameworkRoot}`,
+      'dazscript-types': '^1.0.1',
+    },
+    devDependencies: {},
+  }, null, 2));
+
+  writeFile(path.join(options.fixtureRoot, 'dazscript.config.ts'), [
+    "import { defineConfig } from 'dazscript-framework/config';",
+    '',
+    'export default defineConfig({',
+    "  scriptsPath: './src',",
+    "  outDir: './out',",
+    "  defaultMenuPath: '/DazScriptFramework/Integration',",
+    `  appDataPath: '${options.appDataPath}',`,
+    `  bundleName: '${options.bundleName}'`,
+    '});',
+    '',
+  ].join('\n'));
+
+  writeFile(path.join(options.fixtureRoot, 'tsconfig.json'), JSON.stringify({
+    compilerOptions: {
+      target: 'ES5',
+      baseUrl: '.',
+      ignoreDeprecations: '5.0',
+      lib: ['ES5'],
+      experimentalDecorators: true,
+      emitDecoratorMetadata: true,
+      noLib: false,
+      useDefineForClassFields: false,
+      module: 'ESNext',
+      paths: {
+        '@dst/*': ['node_modules/dazscript-types/src/types/*'],
+        '@dsf/*': ['node_modules/dazscript-framework/src/*'],
+      },
+      declaration: false,
+      inlineSourceMap: false,
+      removeComments: true,
+      preserveConstEnums: true,
+      esModuleInterop: true,
+      forceConsistentCasingInFileNames: true,
+      strict: false,
+      strictNullChecks: false,
+      strictPropertyInitialization: false,
+      noImplicitAny: false,
+      strictFunctionTypes: true,
+      alwaysStrict: true,
+      skipLibCheck: true,
+    },
+    include: [
+      'node_modules/dazscript-types/src/types/**/*',
+      'src/**/*',
+    ],
+  }, null, 2));
+
+  fs.copyFileSync(options.fixturePath, path.join(options.fixtureRoot, 'src', `${options.fixtureName}.dsa.ts`));
+  run('npm', ['install', '--ignore-scripts'], { cwd: options.fixtureRoot });
+  run('npm', ['run', 'build'], { cwd: options.fixtureRoot });
+}
+
+function runDazFixture(options) {
+  const launcherPath = path.join(options.fixtureRoot, 'out', `${options.fixtureName}.dsa`);
+  if (!fs.existsSync(launcherPath)) {
+    throw new Error(`generated launcher was not found: ${launcherPath}`);
+  }
+
+  const dazArgs = [
+    '-headless',
+    '-noPrompt',
+    '-scriptArg',
+    normalizeForDaz(options.resultPath),
+  ];
+
+  if (options.contentPath) {
+    dazArgs.push('-scriptArg', options.contentPath);
+  }
+
+  dazArgs.push('-script', normalizeForDaz(launcherPath));
+
+  const useWine = process.platform !== 'win32' && /\.exe$/i.test(options.dazStudioExe);
+  const command = useWine ? 'wine' : options.dazStudioExe;
+  const commandArgs = useWine ? [options.dazStudioExe].concat(dazArgs) : dazArgs;
+
+  console.log(`[dazscript integration] launching DAZ: ${useWine ? `${command} ${options.dazStudioExe}` : command}`);
+  run(command, commandArgs, {
+    cwd: options.fixtureRoot,
+    env: options.env,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+function readIntegrationResult(resultPath) {
+  if (!fs.existsSync(resultPath)) {
+    throw new Error(`DAZ did not write result JSON: ${resultPath}`);
+  }
+
+  let result;
+  try {
+    result = JSON.parse(fs.readFileSync(resultPath, 'utf8'));
+  }
+  catch (error) {
+    throw new Error(`could not parse result JSON: ${error}`);
+  }
+
+  if (!result || result.ok !== true) {
+    const failures = result && result.failures ? result.failures : ['unknown DAZ integration failure'];
+    throw new Error(`DAZ integration assertions failed:\n${failures.map((item) => `- ${item}`).join('\n')}\n\nResult: ${resultPath}`);
+  }
+
+  return result;
+}
+
+async function runIntegration(rawOptions, injectedEnv, cwd) {
+  const env = { ...(injectedEnv || process.env) };
+  const projectRoot = path.resolve(cwd || process.cwd());
+  const envFile = path.resolve(projectRoot, (rawOptions && rawOptions.envFile) || '.env.integration.local');
+  loadEnvFile(envFile, env);
+
+  const options = resolveIntegrationOptions(projectRoot, rawOptions, env);
+  buildFixtureProject(options);
+  runDazFixture(options);
+  const result = readIntegrationResult(options.resultPath);
+  console.log(`[dazscript integration] passed: ${options.resultPath}`);
+  return result;
+}
+
+module.exports = {
+  loadEnvFile,
+  normalizeForDaz,
+  readIntegrationResult,
+  resolveIntegrationOptions,
+  buildFixtureProject,
+  runDazFixture,
+  runIntegration,
+};

package/dist/scripts/launchers.js

@@ -96,7 +96,13 @@ function makeLauncherSource(implementationRelativePath, appDataImplementationRel
     `        MessageBox.warning('Unable to load script implementation:\\n' + implementationPath, 'Script Load Error', '&OK;', '');`,
     '        script.deleteLater();',
     '    } else {',
-    "        var args = typeof getArguments == 'function' ? getArguments() : [];",
+    '        var args = [];',
+    "        if (typeof getArguments == 'function') {",
+    '            args = getArguments();',
+    '        }',
+    '        if (!args || args.length === 0) {',
+    '            args = App.scriptArgs || [];',
+    '        }',
     '        script.execute(args);',
     '        script.deleteLater();',
     '    }',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",
@@ -13,6 +13,7 @@
     "icons": "node ./dist/scripts/cli.js icons --out-dir ./out",
     "installer": "node ./dist/scripts/cli.js installer --scripts-path ./src/examples --menu-path /DazScriptFramework",
     "test": "vitest run",
+    "test:integration": "node ./dist/scripts/cli.js integration --fixture ./test/integration/fixtures/framework-integration.dsa.ts --require-content",
     "test:watch": "vitest"
   },
   "bin": {

package/src/helpers/progress-helper.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const started: Array<{
+    info: string
+    totalSteps: number
+    isCancellable: boolean
+    showTimeElapsed: boolean
+}> = []
+const steps: number[] = []
+
+const installProgressGlobals = (cancelled = false): void => {
+    vi.stubGlobal('startProgress', (info: string, totalSteps: number, isCancellable: boolean, showTimeElapsed: boolean) => {
+        started.push({ info, totalSteps, isCancellable, showTimeElapsed })
+    })
+    vi.stubGlobal('stepProgress', (count = 1) => {
+        steps.push(count)
+    })
+    vi.stubGlobal('finishProgress', vi.fn())
+    vi.stubGlobal('progressIsCancelled', () => cancelled)
+    vi.stubGlobal('processEvents', vi.fn())
+}
+
+beforeEach(() => {
+    started.length = 0
+    steps.length = 0
+    vi.resetModules()
+})
+
+afterEach(() => {
+    vi.unstubAllGlobals()
+})
+
+describe('withProgress', () => {
+    it('starts progress, exposes a manual step handle, and finishes after callback returns', async () => {
+        installProgressGlobals()
+        const { withProgress } = await import('./progress-helper')
+
+        const result = withProgress('Manual Work', 4, (progress) => {
+            progress.step()
+            progress.step(2)
+            return 'done'
+        })
+
+        expect(result).toBe('done')
+        expect(started).toEqual([
+            {
+                info: 'Manual Work',
+                totalSteps: 4,
+                isCancellable: true,
+                showTimeElapsed: true,
+            },
+        ])
+        expect(steps).toEqual([1, 2])
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+
+    it('finishes progress when the callback throws', async () => {
+        installProgressGlobals()
+        const { withProgress } = await import('./progress-helper')
+
+        expect(() => withProgress('Manual Work', 2, () => {
+            throw new Error('failed phase')
+        })).toThrow('failed phase')
+
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+
+    it('reports cancellation consistently with cancellable progress', async () => {
+        installProgressGlobals(true)
+        const { withProgress } = await import('./progress-helper')
+
+        let callbackCancelled = false
+        withProgress('Manual Work', 2, (progress) => {
+            callbackCancelled = progress.isCancelled()
+            progress.step()
+        })
+
+        expect(callbackCancelled).toBe(true)
+        expect(processEvents).toHaveBeenCalledTimes(1)
+        expect(steps).toEqual([])
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe('progress', () => {
+    it('finishes progress when an item callback stops the loop', async () => {
+        installProgressGlobals()
+        const { progress } = await import('./progress-helper')
+
+        progress('Array Work', [1, 2, 3], (item: number) => item !== 2)
+
+        expect(steps).toEqual([1])
+        expect(finishProgress).toHaveBeenCalledTimes(1)
+    })
+})

package/src/helpers/progress-helper.ts

@@ -1,5 +1,29 @@
 import { status } from '@dsf/common/log';
 
+export type ProgressOptions = {
+    isCancellable?: boolean
+    showTimeElapsed?: boolean
+    totalSteps?: number
+}
+
+export type ProgressHandle = {
+    step: (count?: number) => boolean
+    isCancelled: () => boolean
+}
+
+const defaultProgressOptions = (totalSteps: number, options?: ProgressOptions): Required<ProgressOptions> => ({
+    isCancellable: true,
+    showTimeElapsed: true,
+    totalSteps,
+    ...options
+})
+
+const reportInfo = (info: string | string[]): string => {
+    const infoMessage = Array.isArray(info) ? '' : info;
+    if (Array.isArray(info)) info.forEach(line => status(line));
+    return infoMessage;
+}
+
 /**
  * Displays a progress dialog to the user if one is not already being displayed and starts a progress tracking operation.
  * @param info The string to display in the progress dialog as the current description of the operation.
@@ -10,43 +34,79 @@ import { status } from '@dsf/common/log';
  * @param totalSteps The number of progress steps for the operation to be complete.
  */
 export const progress = <T>(info: string | string[], items: T[], callback: (item: T) => boolean | void,
-    options?: { isCancellable?: boolean, showTimeElapsed?: boolean, totalSteps?: number }) => {
+    options?: ProgressOptions) => {
 
-    options = {
-        isCancellable: true,
-        showTimeElapsed: true,
-        totalSteps: items.length,
-        ...options
-    };
+    const resolvedOptions = defaultProgressOptions(items.length, options);
 
-    const infoMessage = Array.isArray(info) ? '' : info;
-    startProgress(infoMessage, options.totalSteps, options.isCancellable, options.showTimeElapsed);
+    const infoMessage = reportInfo(info);
+    startProgress(infoMessage, resolvedOptions.totalSteps, resolvedOptions.isCancellable, resolvedOptions.showTimeElapsed);
 
-    if (Array.isArray(info)) info.forEach(line => status(line));
+    try {
+        // const total = Math.max(1, options.totalSteps ?? items.length);
+        // let lastQuarter = -1; // -1 so first boundary triggers
+
+        for (let i = 0; i < items.length; i++) {
+            // cancellation
+            if (resolvedOptions.isCancellable && progressIsCancelled()) {
+                processEvents(); // flush once on cancel
+                break;
+            }
+
+            // work
+            if (callback && callback(items[i]) === false) break;
 
-    // const total = Math.max(1, options.totalSteps ?? items.length);
-    // let lastQuarter = -1; // -1 so first boundary triggers
+            // progress
+            stepProgress(1);
 
-    for (let i = 0; i < items.length; i++) {
-        // cancellation
-        if (options.isCancellable && progressIsCancelled()) {
-            processEvents(); // flush once on cancel
-            break;
+            // 25/50/75/100 checkpoints
+            // const quarter = Math.floor(((i + 1) * 2) / total); // 0..4
+            // if (quarter > lastQuarter) {
+            //     processEvents();
+            //     lastQuarter = quarter;
+            // }
         }
+    }
+    finally {
+        finishProgress();
+    }
+}
 
-        // work
-        if (callback && callback(items[i]) === false) return;
+/**
+ * Starts a progress operation for multi-phase work that does not map to a single item array.
+ * Uses script-level cleanup for normal returns and catchable script exceptions; host crashes or native aborts can still bypass script cleanup.
+ * @param info The string to display in the progress dialog as the current description of the operation.
+ * @param totalSteps The number of progress steps for the operation to be complete.
+ * @param callback The function to run with a manual progress handle.
+ * @param options Progress dialog options consistent with the array-driven progress helper.
+ */
+export const withProgress = <T>(info: string | string[], totalSteps: number, callback: (progress: ProgressHandle) => T,
+    options?: Omit<ProgressOptions, 'totalSteps'>): T => {
 
-        // progress
-        stepProgress(1);
+    const resolvedOptions = defaultProgressOptions(totalSteps, options);
+    const infoMessage = reportInfo(info);
+    startProgress(infoMessage, resolvedOptions.totalSteps, resolvedOptions.isCancellable, resolvedOptions.showTimeElapsed);
 
-        // 25/50/75/100 checkpoints
-        // const quarter = Math.floor(((i + 1) * 2) / total); // 0..4
-        // if (quarter > lastQuarter) {
-        //     processEvents();
-        //     lastQuarter = quarter;
-        // }
+    let flushedCancellation = false;
+    const handle: ProgressHandle = {
+        isCancelled: () => {
+            const cancelled = resolvedOptions.isCancellable && Boolean(progressIsCancelled());
+            if (cancelled && !flushedCancellation) {
+                processEvents();
+                flushedCancellation = true;
+            }
+            return cancelled;
+        },
+        step: (count: number = 1) => {
+            if (handle.isCancelled()) return false;
+            stepProgress(count);
+            return true;
+        }
     }
 
-    finishProgress();
-}
+    try {
+        return callback(handle);
+    }
+    finally {
+        finishProgress();
+    }
+}

package/src/helpers/script-helper.ts

@@ -17,7 +17,12 @@ export const getScriptPath = (): string => {
 
 export const getScriptArguments = (): any[] => {
     try {
-        return typeof getArguments === 'function' ? getArguments() : []
+        if (typeof getArguments === 'function') {
+            const args = getArguments()
+            if (args && args.length > 0) return args
+        }
+
+        return App.scriptArgs ?? []
     }
     catch (e) {
         return []