dazscript-framework 1.0.3 → 1.0.5

package/README.md

@@ -2,6 +2,28 @@
 
 **DazScript Framework** is a TypeScript toolkit for writing [Daz Studio](https://www.daz3d.com/daz-studio) scripts. It layers a full TypeScript development experience on top of [DAZ Script](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/start) (Qt Script / ECMAScript 5.1), and ships a fluent dialog builder so you can build UIs in code without touching the Qt widget API directly.
 
+## Table of Contents
+
+- [Why use it?](#why-use-it)
+- [Quick Start: Hello World](#quick-start-hello-world)
+- [Quick Start: A Simple Dialog](#quick-start-a-simple-dialog)
+- [Documentation](#documentation)
+  - [Installation & Setup](#installation--setup)
+  - [Project Configuration](#project-configuration)
+  - [The `action(...)` Entrypoint](#the-action-entrypoint)
+  - [Build Output: Launcher Shims](#build-output-launcher-shims)
+  - [Generated Setup Script](#generated-setup-script)
+  - [Setup Keyboard Shortcuts](#setup-keyboard-shortcuts)
+  - [Action-Level Bundles](#action-level-bundles)
+  - [Building UIs: Dialogs & Observables](#building-uis-dialogs--observables)
+  - [Observables](#observables)
+  - [Dialog Builder Reference](#dialog-builder-reference)
+  - [Available Helpers](#available-helpers)
+  - [Directory Structure](#directory-structure)
+  - [Development & Publishing](#development--publishing)
+- [Resources](#resources)
+- [Examples](#examples)
+
 ## Why use it?
 
 DAZ Script gives you direct access to the entire Daz Studio API. The DazScript Framework builds on that foundation and adds:
@@ -10,7 +32,7 @@ DAZ Script gives you direct access to the entire Daz Studio API. The DazScript F
 - **Fast UI development** — a fluent builder API lets you describe dialogs declaratively without touching the Qt widget API by hand.
 - **Two-way data binding** — link your data model to UI controls so they stay in sync automatically. The user types in a field and your model updates; you update the model in code and the UI reflects it instantly. No manual synchronization needed.
 - **One-command build** — `npm run build` compiles TypeScript to `.dsa` files that Daz Studio runs directly.
-- **Stable launcher shims** — built scripts use a two-level layout so iterating on your code never requires reinstalling actions in Daz Studio.
+- **Stable launcher shims** — built scripts use a launcher/implementation layout so iterating on your code never requires reinstalling actions in Daz Studio.
 - **Automated installer generation** — `npm run installer` produces a full setup dialog by reading action metadata from your source code.
 
 ---
@@ -31,7 +53,7 @@ npm install dazscript-framework dazscript-types
 npx dazscript init
 ```
 
-Follow the prompt for your AppData author namespace (e.g. `YourName/my-project`). This creates `dazscript.config.ts`, `tsconfig.json`, and wires the `build`, `watch`, `icons`, and `installer` scripts into `package.json`.
+Follow the prompt for your AppData author namespace (e.g. `YourName/my-project`). This creates `dazscript.config.ts`, `tsconfig.json`, and wires the `build`, `build:encrypted`, `watch`, `encrypt`, `icons`, and `installer` scripts into `package.json`.
 
 ### 3. Write the script
 
@@ -137,7 +159,7 @@ If `--app-data-path` is not provided, `init` prompts for the AppData author name
 This generates:
 - `dazscript.config.ts`
 - `tsconfig.json`
-- `package.json` script wiring for `build`, `watch`, `icons`, and `installer`
+- `package.json` script wiring for `build`, `build:encrypted`, `watch`, `encrypt`, `icons`, and `installer`
 
 Available `init` flags:
 
@@ -222,11 +244,21 @@ action({ text: 'My Script' }, MyScript);
 Each built action produces two files:
 
 - `out/<script>.dsa` — the stable **launcher** registered with Daz Studio (menus, toolbars, shortcuts)
-- `out/<folder>/lib/<script-name>/script.dsa` — the **implementation bundle** the launcher executes
+- `out/<folder>/lib/<script-name>/<script-name>.dsa` — the **implementation bundle** the launcher executes
 
 When you rebuild, only the implementation bundle changes. The launcher path stays stable, so re-registering the action in Daz Studio is normally not required.
 
-At runtime the launcher looks for the local `lib/` bundle first, then falls back to `App.getAppDataPath()/<appDataPath>`.
+At runtime the launcher looks for a local encrypted `script.dse` bundle first, then the local `script.dsa` bundle, then the same encrypted/plain fallback paths under `App.getAppDataPath()/<appDataPath>`.
+
+To encrypt implementation bundles before packaging, run the build and then call Daz Studio through the framework CLI:
+
+```bash
+npx dazscript encrypt --out-dir ./out --daz-studio "C:/Program Files/DAZ 3D/DAZStudio4/DAZStudio.exe"
+```
+
+The `encrypt` command launches Daz Studio with `-headless -noPrompt`, converts each implementation bundle under `out/**/lib/**/*.dsa` to a matching `.dse` file, and deletes the source `.dsa` after the matching encrypted file is written. Add `--keep-source` to leave the plain implementation bundles in place.
+
+Individual script packages can wrap this command in `package.json` scripts such as `npm run encrypt` or `npm run build:encrypted` so release packaging does not depend on remembering the full Daz Studio executable argument.
 
 ---
 

package/dist/scripts/cli.js

@@ -6,6 +6,7 @@ const readline = require('readline');
 const { runWebpack } = require('./build');
 const { loadConfig } = require('./config-loader');
 const { copyIcons } = require('./icons');
+const { runEncrypt } = require('./encrypt');
 const { generateInstallerFiles } = require('./install-generator');
 const { initProject } = require('./init');
 
@@ -16,14 +17,18 @@ Commands:
   init                Scaffold a DazScript project in the current directory
   build               Build DazScript files
   watch               Build and watch DazScript files
+  encrypt             Encrypt built implementation bundles through Daz Studio
   icons               Copy png assets into the output directory
   installer           Generate Install.dsa.ts and Uninstall.dsa.ts
 
-Options for init:
+Options:
   --menu-path <path>    Default menu path. Default: /MyScripts
   --scripts-path <path> Source directory to scan. Default: ./src
   --out-dir <path>      Build output directory. Default: ./out
   --app-data-path <path> AppData namespace used by launcher fallbacks. Example: Author/Product
+  --daz-studio <path>   Daz Studio executable for encrypt
+  --keep-source         Keep source script.dsa files after encrypting
+  --timeout-ms <value>  Daz Studio encrypt timeout. Default: 300000
   --force               Overwrite generated files
   --help                Show this message
 `);
@@ -110,6 +115,23 @@ function parseOptions(args, defaults) {
       continue;
     }
 
+    if (arg === '--daz-studio') {
+      options.dazStudio = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--keep-source') {
+      options.keepSource = true;
+      continue;
+    }
+
+    if (arg === '--timeout-ms') {
+      options.timeoutMs = Number(args[index + 1]);
+      index += 1;
+      continue;
+    }
+
     if (arg === '--file') {
       options.file = args[index + 1];
       index += 1;
@@ -158,6 +180,9 @@ async function main(argv) {
     outDir: undefined,
     appDataPath: undefined,
     file: undefined,
+    dazStudio: undefined,
+    keepSource: false,
+    timeoutMs: undefined,
   });
 
   if (options.help) {
@@ -192,6 +217,11 @@ async function main(argv) {
     return;
   }
 
+  if (command === 'encrypt') {
+    runEncrypt(workdir, resolvedOptions);
+    return;
+  }
+
   if (command === 'icons') {
     copyIcons(workdir, resolvedOptions);
     return;

package/dist/scripts/encrypt.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function toDazPath(filePath) {
+  return path.resolve(filePath).replace(/\\/g, '/');
+}
+
+function findImplementationScripts(dir) {
+  const scripts = [];
+
+  function visit(currentDir) {
+    if (!fs.existsSync(currentDir)) {
+      return;
+    }
+
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const entryPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        visit(entryPath);
+        continue;
+      }
+
+      if (
+        entry.isFile() &&
+        entry.name.endsWith('.dsa') &&
+        entryPath.split(path.sep).includes('lib')
+      ) {
+        scripts.push(entryPath);
+      }
+    }
+  }
+
+  visit(dir);
+  return scripts;
+}
+
+function makeConverterScript() {
+  return [
+    '(function(){',
+    '    function log(message) { print("[dazscript encrypt] " + message); }',
+    '    function fail(message) {',
+    '        print("[dazscript encrypt] ERROR " + message);',
+    '        App.quit();',
+    '    }',
+    '    function splitList(value) {',
+    '        if (!value) return [];',
+    '        return String(value).split("|");',
+    '    }',
+    '    function removeSourceFile(sourcePath) {',
+    '        var sourceFile = new DzFile(sourcePath);',
+    '        if (sourceFile.exists() && !sourceFile.remove()) {',
+    '            log("warning: encrypted but could not delete " + sourcePath);',
+    '        }',
+    '        sourceFile.deleteLater();',
+    '    }',
+    '    var args = App.scriptArgs;',
+    '    var sourceList = splitList(args[0]);',
+    '    var deleteSources = String(args[1]) == "delete";',
+    '    if (!sourceList.length) {',
+    '        log("no implementation scripts found");',
+    '        App.quit();',
+    '        return;',
+    '    }',
+    '    var failures = 0;',
+    '    for (var i = 0; i < sourceList.length; i += 1) {',
+    '        var sourcePath = sourceList[i];',
+    '        var destPath = sourcePath.replace(/\\.dsa$/i, ".dse");',
+    '        var script = new DzScript();',
+    '        log("encrypt " + sourcePath);',
+    '        if (!script.loadFromFile(sourcePath)) {',
+    '            failures += 1;',
+    '            log("failed to load " + sourcePath);',
+    '            script.deleteLater();',
+    '            continue;',
+    '        }',
+    '        if (!script.checkSyntax()) {',
+    '            failures += 1;',
+    '            log("syntax error in " + sourcePath + " line " + script.errorLine() + ": " + script.errorMessage());',
+    '            script.deleteLater();',
+    '            continue;',
+    '        }',
+    '        var writeError = script.saveFile(destPath, DzScript.EncDAZScriptFile);',
+    '        script.deleteLater();',
+    '        if (Number(writeError) != 0) {',
+    '            failures += 1;',
+    '            log("failed to save " + destPath + " error=" + writeError);',
+    '            continue;',
+    '        }',
+    '        if (deleteSources) {',
+    '            removeSourceFile(sourcePath);',
+    '        }',
+    '        log("wrote " + destPath);',
+    '    }',
+    '    if (failures) {',
+    '        fail(String(failures) + " script(s) failed");',
+    '        return;',
+    '    }',
+    '    log("complete");',
+    '    App.quit();',
+    '})();',
+    '',
+  ].join('\n');
+}
+
+function runEncrypt(workdir, options) {
+  if (!options.dazStudio) {
+    throw new Error('Missing required option: --daz-studio <path>');
+  }
+
+  const outDir = path.resolve(workdir, options.outDir || './out');
+  const dazStudioPath = path.resolve(workdir, options.dazStudio);
+
+  if (!fs.existsSync(dazStudioPath)) {
+    throw new Error(`Daz Studio executable not found: ${dazStudioPath}`);
+  }
+
+  if (!fs.existsSync(outDir)) {
+    throw new Error(`Output directory not found: ${outDir}`);
+  }
+
+  const implementationScripts = findImplementationScripts(outDir);
+  if (!implementationScripts.length) {
+    console.log(`[dazscript encrypt] no implementation scripts found under ${outDir}`);
+    return;
+  }
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dazscript-encrypt-'));
+  const converterPath = path.join(tempDir, 'encrypt-output.dsa');
+  fs.writeFileSync(converterPath, makeConverterScript(), 'utf8');
+
+  const args = [
+    '-headless',
+    '-noPrompt',
+    '-scriptArg',
+    implementationScripts.map(toDazPath).join('|'),
+    '-scriptArg',
+    options.keepSource ? 'keep' : 'delete',
+    toDazPath(converterPath),
+  ];
+
+  console.log(`[dazscript encrypt] encrypting ${implementationScripts.length} implementation script(s)`);
+  const result = spawnSync(dazStudioPath, args, {
+    encoding: 'utf8',
+    stdio: 'inherit',
+    timeout: options.timeoutMs || 300000,
+  });
+
+  fs.rmSync(tempDir, { recursive: true, force: true });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`Daz Studio exited with code ${result.status}`);
+  }
+
+  const missingOutputs = implementationScripts.filter((scriptPath) => {
+    const encryptedPath = scriptPath.replace(/\.dsa$/i, '.dse');
+    return !fs.existsSync(encryptedPath);
+  });
+
+  if (missingOutputs.length) {
+    throw new Error(
+      'Daz Studio did not produce encrypted output for:\n' +
+        missingOutputs.map((scriptPath) => `  ${scriptPath}`).join('\n')
+    );
+  }
+}
+
+module.exports = {
+  runEncrypt,
+};

package/dist/scripts/init.js

@@ -93,8 +93,10 @@ function updatePackageJson(workdir, options) {
     ...(packageJson.scripts || {}),
     prebuild: 'npm run installer',
     build: 'dazscript build',
+    'build:encrypted': 'npm run build && npm run encrypt',
     postbuild: 'npm run icons',
     watch: 'dazscript watch',
+    encrypt: 'dazscript encrypt --out-dir ./out --daz-studio "C:\\Program Files\\DAZ 3D\\DAZStudio4\\DAZStudio.exe"',
     icons: 'dazscript icons',
     installer: 'dazscript installer',
   };

package/dist/scripts/launchers.js

@@ -16,17 +16,40 @@ function getActionOutputPath(workdir, outDir, sourceFile) {
   return relativeSourceFile.replace(/\.ts$/, '');
 }
 
-function getImplementationRelativePath(outputRelativePath) {
+function getImplementationRelativePath(outputRelativePath, extension = 'dsa') {
   const outputDirectory = path.posix.dirname(outputRelativePath);
   const outputBaseName = path.posix.basename(outputRelativePath, '.dsa');
   const implementationDirectory = outputDirectory === '.'
     ? path.posix.join('lib', outputBaseName)
     : path.posix.join(outputDirectory, 'lib', outputBaseName);
 
-  return path.posix.join(implementationDirectory, 'script.dsa');
+  return path.posix.join(implementationDirectory, `${outputBaseName}.${extension}`);
+}
+
+function getFlatImplementationRelativePath(outputRelativePath, extension = 'dsa') {
+  const outputDirectory = path.posix.dirname(outputRelativePath);
+  const outputBaseName = path.posix.basename(outputRelativePath, '.dsa');
+  const implementationDirectory = outputDirectory === '.'
+    ? 'lib'
+    : path.posix.join(outputDirectory, 'lib');
+
+  return path.posix.join(implementationDirectory, `${outputBaseName}.${extension}`);
+}
+
+function getLegacyImplementationRelativePath(outputRelativePath, extension = 'dsa') {
+  const outputDirectory = path.posix.dirname(outputRelativePath);
+  const outputBaseName = path.posix.basename(outputRelativePath, '.dsa');
+  const implementationDirectory = outputDirectory === '.'
+    ? path.posix.join('lib', outputBaseName)
+    : path.posix.join(outputDirectory, 'lib', outputBaseName);
+
+  return path.posix.join(implementationDirectory, `script.${extension}`);
 }
 
 function makeLauncherSource(implementationRelativePath, appDataImplementationRelativePath) {
+  const encryptedImplementationRelativePath = implementationRelativePath.replace(/\.dsa$/, '.dse');
+  const encryptedAppDataImplementationRelativePath = appDataImplementationRelativePath.replace(/\.dsa$/, '.dse');
+
   return [
     '// Auto-generated launcher shim.',
     '// The installed Daz action points at this stable file.',
@@ -34,7 +57,9 @@ function makeLauncherSource(implementationRelativePath, appDataImplementationRel
     '// and from the AppData fallback location second.',
     '',
     `var implementationRelativePath = '${implementationRelativePath}';`,
+    `var encryptedImplementationRelativePath = '${encryptedImplementationRelativePath}';`,
     `var appDataImplementationRelativePath = '${appDataImplementationRelativePath}';`,
+    `var encryptedAppDataImplementationRelativePath = '${encryptedAppDataImplementationRelativePath}';`,
     'var launcherFileName = getScriptFileName();',
     'var launcherInfo = new DzFileInfo(launcherFileName);',
     'var launcherDirectory = typeof launcherInfo.canonicalPath == "function"',
@@ -42,10 +67,20 @@ function makeLauncherSource(implementationRelativePath, appDataImplementationRel
     '    : launcherInfo.path();',
     'launcherInfo.deleteLater();',
     '',
-    "var implementationPath = launcherDirectory + '/' + implementationRelativePath;",
+    "var implementationPath = launcherDirectory + '/' + encryptedImplementationRelativePath;",
     'var implementationFile = new DzFile(implementationPath);',
     'if (!implementationFile.exists()) {',
     '    implementationFile.deleteLater();',
+    "    implementationPath = launcherDirectory + '/' + implementationRelativePath;",
+    '    implementationFile = new DzFile(implementationPath);',
+    '}',
+    'if (!implementationFile.exists()) {',
+    '    implementationFile.deleteLater();',
+    "    implementationPath = App.getAppDataPath() + '/' + encryptedAppDataImplementationRelativePath;",
+    '    implementationFile = new DzFile(implementationPath);',
+    '}',
+    'if (!implementationFile.exists()) {',
+    '    implementationFile.deleteLater();',
     "    implementationPath = App.getAppDataPath() + '/' + appDataImplementationRelativePath;",
     '    implementationFile = new DzFile(implementationPath);',
     '}',
@@ -74,6 +109,14 @@ function ensureParentDir(filePath) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
 
+function removeEmptyDir(dirPath) {
+  try {
+    fs.rmdirSync(dirPath);
+  } catch (_err) {
+    // Directory is missing or still contains user/generated files.
+  }
+}
+
 function createActionLaunchers(workdir, options) {
   const outDir = path.resolve(workdir, options.outDir || './out');
   const appDataPath = validateAppDataPath(options.appDataPath, workdir);
@@ -86,15 +129,60 @@ function createActionLaunchers(workdir, options) {
     const launcherPath = path.join(outDir, outputRelativePath);
     const implementationRelativePath = getImplementationRelativePath(outputRelativePath);
     const implementationPath = path.join(outDir, implementationRelativePath);
+    const encryptedImplementationPath = path.join(
+      outDir,
+      getImplementationRelativePath(outputRelativePath, 'dse')
+    );
+    const legacyImplementationPath = path.join(
+      outDir,
+      getLegacyImplementationRelativePath(outputRelativePath)
+    );
+    const legacyEncryptedImplementationPath = path.join(
+      outDir,
+      getLegacyImplementationRelativePath(outputRelativePath, 'dse')
+    );
+    const flatImplementationPath = path.join(
+      outDir,
+      getFlatImplementationRelativePath(outputRelativePath)
+    );
+    const flatEncryptedImplementationPath = path.join(
+      outDir,
+      getFlatImplementationRelativePath(outputRelativePath, 'dse')
+    );
 
     if (!fs.existsSync(launcherPath)) {
       return;
     }
 
+    if (path.resolve(launcherPath) === path.resolve(implementationPath)) {
+      throw new Error(
+        `[dazscript] Launcher path collides with implementation path: ${implementationRelativePath}. ` +
+        `Move the source action out of a lib/ folder or use a different script name.`
+      );
+    }
+
     ensureParentDir(implementationPath);
     if (fs.existsSync(implementationPath)) {
       fs.unlinkSync(implementationPath);
     }
+    if (fs.existsSync(encryptedImplementationPath)) {
+      fs.unlinkSync(encryptedImplementationPath);
+    }
+    if (fs.existsSync(legacyImplementationPath)) {
+      fs.unlinkSync(legacyImplementationPath);
+    }
+    if (fs.existsSync(legacyEncryptedImplementationPath)) {
+      fs.unlinkSync(legacyEncryptedImplementationPath);
+    }
+    if (fs.existsSync(flatImplementationPath)) {
+      fs.unlinkSync(flatImplementationPath);
+    }
+    if (fs.existsSync(flatEncryptedImplementationPath)) {
+      fs.unlinkSync(flatEncryptedImplementationPath);
+    }
+    if (path.resolve(path.dirname(legacyImplementationPath)) !== path.resolve(path.dirname(implementationPath))) {
+      removeEmptyDir(path.dirname(legacyImplementationPath));
+    }
 
     fs.renameSync(launcherPath, implementationPath);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",