dazscript-framework 0.2.4 → 0.2.5

package/README.md

@@ -13,7 +13,7 @@ The **DazScript Framework** is a TypeScript-based framework for writing Daz Stud
 ## Features
 
 - TypeScript support with full IntelliSense.
-- A powerful set of decorators and helper methods for building interactive scripts.
+- A lightweight `action(...)` entrypoint plus helper methods for building interactive scripts.
 - Easy integration with Daz Studio for quick script deployment.
 
 ## Installation
@@ -32,6 +32,8 @@ After installing the package, scaffold the project files:
 npx dazscript init
 ```
 
+If `--app-data-path` is not provided, `init` prompts for the AppData author namespace up front and uses the current folder name as the default product segment.
+
 This generates:
 
 - `dazscript.config.ts`
@@ -43,15 +45,36 @@ The generated package scripts use the framework CLI directly, so consumer projec
 You can customize the generated defaults:
 
 ```bash
-npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out
+npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out --app-data-path YourName/my-project
 ```
 
 - `--menu-path` sets which Daz Studio menu the scripts are added to by default. See [The `action(...)` Entrypoint](#the-action-entrypoint) for how a script can override that with `menuPath`.
 - `--scripts-path` tells the installer generator where to scan for runnable `.dsa.ts` entry files.
 - `--out-dir` sets the webpack build output directory for generated `.dsa` files and copied icons.
+- `--app-data-path` sets the AppData namespace used by launcher fallback resolution. Use a unique `Author/Product` path.
 
 Use `--scripts-path ./src/scripts` for projects shaped like `scripts/common`, where runnable `.dsa.ts` files live under `src/scripts/`. Use `--scripts-path ./src` for packages shaped like `scripts/power-menu`, where runnable `.dsa.ts` files live at the source root.
 
+Set `appDataPath` explicitly in `dazscript.config.ts` for every project. It is required for builds that generate launcher shims:
+
+```typescript
+import { defineConfig } from 'dazscript-framework/config';
+
+export default defineConfig({
+  scriptsPath: './src',
+  outDir: './out',
+  defaultMenuPath: '/MyScripts',
+  appDataPath: 'YourName/my-project',
+});
+```
+
+Built action outputs now use stable launcher shims by default:
+
+- `out/<script>.dsa` is the stable launcher registered with Daz Studio menus, toolbars, and shortcuts
+- `out/<folder>/lib/<script-name>/script.dsa` is the current implementation bundle that the launcher executes
+
+Rebuilding updates the implementation bundle under the shim's sibling `lib/` folder. At runtime, each launcher checks that local `lib/` path first and falls back to `App.getAppDataPath()/...` second. Because the registered launcher path stays stable, action updates normally do not require reinstalling the action in Daz Studio.
+
 ## Usage
 
 ### Quick Start: Hello World
@@ -108,6 +131,15 @@ Common `action(...)` parameters:
 - `description`: a longer description for the action.
 - `bundle`: generates installer and uninstaller entries as a package bundle instead of a single action entry.
 
+When an action is built, the framework emits two files for it:
+
+- the stable launcher at the original output path
+- the implementation bundle under a sibling `lib/<script-name>/script.dsa` path
+
+Generated installers register the launcher path, so menu placement, toolbars, shortcuts, and icons keep pointing at a stable target across rebuilds.
+
+If the local `lib/` implementation is missing, the launcher falls back to the configured `appDataPath`. Builds now require this value and validate it as a unique `Author/Product` style path.
+
 ### Building UIs with Observables & Dialogs
 
 The framework uses a **Model-View pattern** with reactive data bindings:
@@ -302,7 +334,7 @@ my-daz-scripts/
 │   │   ├── my-dialog.ts
 │   │   └── my-dialog-script.dsa.ts
 │   └── config.ts
-├── out/                    # Generated .dsa files (build output)
+├── out/                    # Generated launchers, implementations, and copied icons
 ├── package.json
 ├── tsconfig.json
 └── dazscript.config.ts
@@ -311,8 +343,10 @@ my-daz-scripts/
 **Key points:**
 - Scripts ending in `.dsa.ts` compile to `.dsa` files for Daz Studio
 - Regular `.ts` files are utility, model, or helper classes
+- Built action outputs are split into stable launchers plus sibling `lib/<script-name>/script.dsa` implementations
 - Run `npm run build` to compile TypeScript → Daz Scripts
 - Run `npm run watch` during development for live rebuild
+- Rebuild after script changes; reinstalling Daz actions is usually not required because the launcher path stays stable
 
 ## Development & Publishing
 

package/dist/scripts/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 
+const path = require('path');
+const readline = require('readline');
 const { runWebpack } = require('./build');
 const { loadConfig } = require('./config-loader');
 const { copyIcons } = require('./icons');
@@ -21,11 +23,58 @@ Options for init:
   --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
   --force               Overwrite generated files
   --help                Show this message
 `);
 }
 
+function askQuestion(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer));
+  });
+}
+
+async function resolveInitOptions(workdir, options) {
+  if (options.appDataPath) {
+    return options;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return options;
+  }
+
+  const defaultProductName = path.basename(workdir);
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    let author = '';
+    while (!author) {
+      const answer = await askQuestion(
+        rl,
+        'AppData author namespace (for example Vholf3D): '
+      );
+      author = answer.trim();
+    }
+
+    const productAnswer = await askQuestion(
+      rl,
+      `AppData product namespace [${defaultProductName}]: `
+    );
+    const product = productAnswer.trim() || defaultProductName;
+
+    return {
+      ...options,
+      appDataPath: `${author}/${product}`,
+    };
+  } finally {
+    rl.close();
+  }
+}
+
 function parseOptions(args, defaults) {
   const options = { ...defaults };
 
@@ -55,6 +104,12 @@ function parseOptions(args, defaults) {
       continue;
     }
 
+    if (arg === '--app-data-path') {
+      options.appDataPath = args[index + 1];
+      index += 1;
+      continue;
+    }
+
     if (arg === '--file') {
       options.file = args[index + 1];
       index += 1;
@@ -101,6 +156,7 @@ async function main(argv) {
     menuPath: undefined,
     scriptsPath: undefined,
     outDir: undefined,
+    appDataPath: undefined,
     file: undefined,
   });
 
@@ -109,7 +165,14 @@ async function main(argv) {
     return;
   }
 
+  const commandOptions =
+    command === 'init'
+      ? await resolveInitOptions(workdir, options)
+      : options;
   const resolvedOptions = getResolvedOptions(workdir, options);
+  if (commandOptions !== options) {
+    Object.assign(resolvedOptions, commandOptions);
+  }
   resolvedOptions.menuPath = resolvedOptions.menuPath || '/MyScripts';
   resolvedOptions.scriptsPath = resolvedOptions.scriptsPath || './src';
   resolvedOptions.outDir = resolvedOptions.outDir || './out';

package/dist/scripts/init.js

@@ -49,6 +49,7 @@ export default defineConfig({
   scriptsPath: '${options.scriptsPath}',
   outDir: '${options.outDir}',
   defaultMenuPath: '${options.menuPath}',
+  appDataPath: '${options.appDataPath}',
 });
 `;
 }
@@ -94,11 +95,13 @@ function updatePackageJson(workdir, options) {
 }
 
 function initProject(workdir, rawOptions) {
+  const projectName = path.basename(workdir);
   const options = {
     force: Boolean(rawOptions.force),
     menuPath: normalizePath(rawOptions.menuPath, '/MyScripts'),
     scriptsPath: normalizePath(rawOptions.scriptsPath, './src'),
     outDir: normalizePath(rawOptions.outDir, './out'),
+    appDataPath: normalizePath(rawOptions.appDataPath, `YourName/${projectName}`),
   };
 
   writeFileIfNeeded(

package/dist/scripts/install-generator.js

@@ -141,6 +141,19 @@ function findTopLevelActionCall(content, filePath) {
   return null;
 }
 
+function findActionEntryFiles(workdir, options) {
+  const scriptsPath = options.scriptsPath.endsWith('/')
+    ? options.scriptsPath
+    : `${options.scriptsPath}/`;
+  const matches = glob.sync(`${scriptsPath}/**/*.dsa.ts`, { cwd: workdir });
+
+  return matches.filter((filePath) => {
+    const absolutePath = path.join(workdir, filePath);
+    const content = fs.readFileSync(absolutePath, 'utf-8').toString();
+    return !!findTopLevelActionCall(content, absolutePath);
+  });
+}
+
 function processScript(filePath, container, defaultMenuPath) {
   const fileInfo = path.parse(filePath);
   const content = fs.readFileSync(filePath, 'utf-8').toString();
@@ -231,14 +244,11 @@ function processScripts(paths, container, defaultMenuPath) {
 }
 
 function generateInstallerFiles(workdir, options) {
-  const scriptsPath = options.scriptsPath.endsWith('/')
-    ? options.scriptsPath
-    : `${options.scriptsPath}/`;
   const defaultMenuPath = options.defaultMenuPath.endsWith('/')
     ? options.defaultMenuPath
     : `${options.defaultMenuPath}/`;
   const container = { scripts: [] };
-  const matches = glob.sync(`${scriptsPath}/**/*.dsa.ts`, { cwd: workdir });
+  const matches = findActionEntryFiles(workdir, options);
 
   processScripts(matches, container, defaultMenuPath);
 
@@ -292,4 +302,5 @@ if (require.main === module) {
 
 module.exports = {
   generateInstallerFiles,
+  findActionEntryFiles,
 };

package/dist/scripts/launchers.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { findActionEntryFiles } = require('./install-generator');
+
+function toPosix(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+function getActionOutputPath(workdir, outDir, sourceFile) {
+  const sourceRoot = path.resolve(workdir, 'src');
+  const absoluteSourceFile = path.resolve(workdir, sourceFile);
+  const relativeSourceFile = toPosix(path.relative(sourceRoot, absoluteSourceFile));
+  return relativeSourceFile.replace(/\.ts$/, '');
+}
+
+function getImplementationRelativePath(outputRelativePath) {
+  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');
+}
+
+function validateAppDataPath(appDataPath, workdir) {
+  if (!appDataPath || typeof appDataPath !== 'string') {
+    throw new Error(
+      `[dazscript] Missing required appDataPath in ${workdir}. ` +
+      `Set appDataPath: 'Author/Product' in dazscript.config.ts.`
+    );
+  }
+
+  const normalized = toPosix(appDataPath).trim().replace(/^\/+|\/+$/g, '');
+  const segments = normalized.split('/').filter(Boolean);
+
+  if (segments.length < 2) {
+    throw new Error(
+      `[dazscript] Invalid appDataPath "${appDataPath}" in ${workdir}. ` +
+      `Use at least two segments, for example 'Author/Product'.`
+    );
+  }
+
+  const blockedSegments = new Set([
+    'appdata',
+    'cache',
+    'data',
+    'lib',
+    'libs',
+    'script',
+    'scripts',
+    'temp',
+    'tmp',
+  ]);
+
+  const invalidSegment = segments.find((segment) => blockedSegments.has(segment.toLowerCase()));
+  if (invalidSegment) {
+    throw new Error(
+      `[dazscript] Invalid appDataPath "${appDataPath}" in ${workdir}. ` +
+      `Path segments like "${invalidSegment}" are too generic. Use a unique Author/Product path.`
+    );
+  }
+
+  return normalized;
+}
+
+function makeLauncherSource(implementationRelativePath, appDataImplementationRelativePath) {
+  return [
+    '// Auto-generated launcher shim.',
+    '// The installed Daz action points at this stable file.',
+    '// The current implementation is resolved from the sibling lib/ directory first,',
+    '// and from the AppData fallback location second.',
+    '',
+    `var implementationRelativePath = '${implementationRelativePath}';`,
+    `var appDataImplementationRelativePath = '${appDataImplementationRelativePath}';`,
+    'var launcherFileName = getScriptFileName();',
+    'var launcherInfo = new DzFileInfo(launcherFileName);',
+    'var launcherDirectory = typeof launcherInfo.canonicalPath == "function"',
+    '    ? launcherInfo.canonicalPath()',
+    '    : launcherInfo.path();',
+    'launcherInfo.deleteLater();',
+    '',
+    "var implementationPath = launcherDirectory + '/' + implementationRelativePath;",
+    'var implementationFile = new DzFile(implementationPath);',
+    'if (!implementationFile.exists()) {',
+    '    implementationFile.deleteLater();',
+    "    implementationPath = App.getAppDataPath() + '/' + appDataImplementationRelativePath;",
+    '    implementationFile = new DzFile(implementationPath);',
+    '}',
+    '',
+    'if (!implementationFile.exists()) {',
+    `    MessageBox.warning('Unable to find script implementation:\\n' + implementationPath, 'Missing Script', '&OK;', '');`,
+    '    implementationFile.deleteLater();',
+    '} else {',
+    '    implementationFile.deleteLater();',
+    '',
+    '    var script = new DzScript(implementationPath);',
+    '    if (!script.loadFromFile(implementationPath, true)) {',
+    `        MessageBox.warning('Unable to load script implementation:\\n' + implementationPath, 'Script Load Error', '&OK;', '');`,
+    '        script.deleteLater();',
+    '    } else {',
+    "        var args = typeof getArguments == 'function' ? getArguments() : [];",
+    '        script.execute(args);',
+    '        script.deleteLater();',
+    '    }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+function ensureParentDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function createActionLaunchers(workdir, options) {
+  const outDir = path.resolve(workdir, options.outDir || './out');
+  const appDataPath = validateAppDataPath(options.appDataPath, workdir);
+  const actionEntryFiles = findActionEntryFiles(workdir, {
+    scriptsPath: options.scriptsPath || './src',
+  });
+
+  actionEntryFiles.forEach((sourceFile) => {
+    const outputRelativePath = getActionOutputPath(workdir, outDir, sourceFile);
+    const launcherPath = path.join(outDir, outputRelativePath);
+    const implementationRelativePath = getImplementationRelativePath(outputRelativePath);
+    const implementationPath = path.join(outDir, implementationRelativePath);
+
+    if (!fs.existsSync(launcherPath)) {
+      return;
+    }
+
+    ensureParentDir(implementationPath);
+    if (fs.existsSync(implementationPath)) {
+      fs.unlinkSync(implementationPath);
+    }
+
+    fs.renameSync(launcherPath, implementationPath);
+
+    const launcherDir = path.dirname(outputRelativePath);
+    const relativeImplementationPath = toPosix(
+      path.relative(launcherDir || '.', implementationRelativePath)
+    );
+    const appDataImplementationRelativePath = toPosix(
+      path.posix.join(appDataPath, implementationRelativePath)
+    );
+
+    fs.writeFileSync(
+      launcherPath,
+      makeLauncherSource(
+        relativeImplementationPath,
+        appDataImplementationRelativePath
+      )
+    );
+  });
+}
+
+module.exports = {
+  createActionLaunchers,
+  validateAppDataPath,
+};

package/package.json

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

package/webpack.config.js

@@ -1,10 +1,33 @@
 const path = require('path');
 const glob = require('glob');
 const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');
+const { createActionLaunchers, validateAppDataPath } = require('./dist/scripts/launchers');
+const { loadConfig } = require('./dist/scripts/config-loader');
+
+class ActionLauncherPlugin {
+  constructor(options) {
+    this.options = options;
+  }
+
+  apply(compiler) {
+    compiler.hooks.done.tap('ActionLauncherPlugin', () => {
+      createActionLaunchers(this.options.workdir, {
+        outDir: this.options.outDir,
+        scriptsPath: this.options.scriptsPath,
+        appDataPath: this.options.appDataPath,
+      });
+    });
+  }
+}
 
 module.exports = (env, argv) => {
   const projectRoot =
     env && env.context ? path.resolve(env.context) : process.cwd();
+  const { config: projectConfig } = loadConfig(projectRoot);
+  const appDataPath = validateAppDataPath(
+    (env && env.appDataPath) || projectConfig.appDataPath,
+    projectRoot
+  );
   const sourceRoot = path.resolve(projectRoot, 'src');
   const projectNodeModules = path.resolve(projectRoot, 'node_modules');
   const frameworkSourceRoot = path.resolve(
@@ -88,5 +111,14 @@ module.exports = (env, argv) => {
         module: false,
       },
     },
+    plugins: [
+      new ActionLauncherPlugin({
+        workdir: projectRoot,
+        outDir: outputPath,
+        scriptsPath:
+          (env && env.scriptsPath) || projectConfig.scriptsPath || './src',
+        appDataPath,
+      }),
+    ],
   };
 };