dazscript-framework 0.1.17 → 0.2.1

package/README.md

@@ -21,76 +21,36 @@ The **DazScript Framework** is a TypeScript-based framework for writing Daz Stud
 To install the **DazScript Framework**, run the following command:
 
 ```bash
-npm install dazscript-framework
+npm install dazscript-framework dazscript-types
 ```
 
 ## Setup
 
-After installing the package, you will need to configure a few files for your project.
+After installing the package, scaffold the project files:
 
-1. **babel.config.js**
-
-   Create the file and add the following content:
-
-   ```javascript
-   const sharedBabelConfig = require('dazscript-framework/babel');
-
-   module.exports = {
-     ...sharedBabelConfig,
-     presets: [...sharedBabelConfig.presets],
-     plugins: [...sharedBabelConfig.plugins],
-   };
-   ```
-
-2. **package.json**
-
-   Add the following scripts to your package.json:
-
-   ```json
-   "scripts": {
-       "prebuild": "npm run installer",
-       "build": "webpack --env outputPath=./out",
-       "postbuild": "npm run icons",
-       "watch": "webpack --env outputPath=./out --watch",
-       "icons": "copyfiles -u 1 src/**/*.png out/",
-       "installer": "node ./node_modules/dazscript-framework/dist/scripts/install-generator.js -p ./src/scripts -m /MyScripts"
-   }
-   ```
+```bash
+npx dazscript init
+```
 
-3. **tsconfig.json**
+This generates:
 
-   Create the file and add the following content:
+- `dazscript.config.ts`
+- `tsconfig.json`
+- `package.json` script wiring for `build`, `watch`, `icons`, and `installer`
 
-   ```json
-   {
-     "extends": "./node_modules/dazscript-framework/tsconfig.json",
-     "compilerOptions": {
-       "baseUrl": "./",
-       "paths": {
-         "shared/*": ["src/shared/*"],
-         "@dst/*": ["node_modules/dazscript-types/*"],
-         "@dsf/*": ["node_modules/dazscript-framework/src/*"]
-       }
-     },
-     "include": ["node_modules/dazscript-types/**/*", "src/**/*"]
-   }
-   ```
+The generated package scripts use the framework CLI directly, so consumer projects do not need their own webpack or Babel setup.
 
-4. **webpack.config.js**
-   Create the file and add the following content:
+You can customize the generated defaults:
 
-   ```javascript
-   const sharedWebpackConfig = require('dazscript-framework/webpack');
+```bash
+npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out
+```
 
-   module.exports = (env, argv) => {
-     const sharedConfig = sharedWebpackConfig(env, argv);
+- `--menu-path` sets which Daz Studio menu the scripts are added to by default. See [The `@action` Decorator](#the-action-decorator) 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.
 
-     return {
-       ...sharedConfig,
-       // You can override or add more customizations here if needed
-     };
-   };
-   ```
+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.
 
 ## Usage
 
@@ -115,6 +75,36 @@ class HelloWorldScript extends BaseScript {
 new HelloWorldScript().exec();
 ```
 
+### The `@action` Decorator
+
+Use `@action(...)` on a script class to register how it should appear in Daz Studio.
+
+```typescript
+@action({
+  text: 'Hello World',
+  menuPath: '#{defaultMenuPath}/Examples',
+  shortcut: 'CTRL+SHIFT+H',
+  toolbar: 'MyToolbar',
+  group: 'Examples',
+  description: 'Runs the Hello World script',
+})
+class HelloWorldScript extends BaseScript {
+    protected run(): void {
+        info('Hello World!');
+    }
+}
+```
+
+Common `@action(...)` parameters:
+
+- `text`: the label shown for the script in Daz Studio.
+- `menuPath`: the menu path where the script should be added. Set it to `false` to skip adding the script to a menu. If omitted, the default menu from `--menu-path` is used.
+- `shortcut`: the keyboard shortcut for the action.
+- `toolbar`: the toolbar name used when the action should appear on a toolbar.
+- `group`: an optional grouping label used by Daz Studio for related actions.
+- `description`: a longer description for the action.
+- `bundle`: generates installer and uninstaller entries as a package bundle instead of a single action entry.
+
 ### Building UIs with Observables & Dialogs
 
 The framework uses a **Model-View pattern** with reactive data bindings:
@@ -318,8 +308,7 @@ my-daz-scripts/
 ├── out/                    # Generated .dsa files (build output)
 ├── package.json
 ├── tsconfig.json
-├── webpack.config.js
-└── babel.config.js
+└── dazscript.config.ts
 ```
 
 **Key points:**

package/babel.config.js

@@ -1,7 +1,7 @@
 module.exports = {
   presets: [
     [
-      '@babel/preset-env',
+      require.resolve('@babel/preset-env'),
       {
         targets: {
           esmodules: true,
@@ -10,24 +10,16 @@ module.exports = {
         include: ['@babel/plugin-transform-class-properties'],
       },
     ],
-    '@babel/preset-typescript',
+    require.resolve('@babel/preset-typescript'),
   ],
   plugins: [
-    '@babel/plugin-transform-class-properties',
-    'babel-plugin-transform-typescript-metadata',
-    ['@babel/plugin-proposal-decorators', { version: 'legacy' }],
-    ['@babel/plugin-transform-arrow-functions'],
-    '@babel/plugin-transform-block-scoping',
-    '@babel/plugin-proposal-class-properties',
-    '@babel/plugin-transform-private-property-in-object',
-    '@babel/plugin-transform-private-methods',
-    [
-      'dazscript-framework/babel/trace-babel-plugin', // Ensure this path is correct
-      { default: false, retainLines: false },
-    ],
-    [
-      'dazscript-framework/babel/trace-log-babel-plugin', // Ensure this path is correct
-      { default: false, retainLines: false },
-    ],
+    require.resolve('@babel/plugin-transform-class-properties'),
+    require.resolve('babel-plugin-transform-typescript-metadata'),
+    [require.resolve('@babel/plugin-proposal-decorators'), { version: 'legacy' }],
+    [require.resolve('@babel/plugin-transform-arrow-functions')],
+    require.resolve('@babel/plugin-transform-block-scoping'),
+    require.resolve('@babel/plugin-proposal-class-properties'),
+    require.resolve('@babel/plugin-transform-private-property-in-object'),
+    require.resolve('@babel/plugin-transform-private-methods'),
   ],
 };

package/dist/config.js

@@ -0,0 +1,9 @@
+'use strict';
+
+function defineConfig(config) {
+  return config;
+}
+
+module.exports = {
+  defineConfig,
+};

package/dist/scripts/build.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const path = require('path');
+const webpack = require('webpack');
+const createWebpackConfig = require('../../webpack.config.js');
+
+function runWebpack(workdir, options) {
+  const env = {
+    context: workdir,
+    outputPath: options.outDir || './out',
+  };
+
+  if (options.file) {
+    env.file = options.file;
+  }
+
+  const config = createWebpackConfig(env, {
+    mode: options.watch ? 'development' : 'production',
+  });
+
+  return new Promise((resolve, reject) => {
+    const compiler = webpack(config);
+
+    const handleStats = (error, stats) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      if (stats.hasErrors()) {
+        reject(new Error(stats.toString({ colors: true })));
+        return;
+      }
+
+      console.log(
+        stats.toString({
+          colors: true,
+          chunks: false,
+          modules: false,
+        })
+      );
+
+      if (!options.watch) {
+        resolve();
+      }
+    };
+
+    if (options.watch) {
+      compiler.watch({}, handleStats);
+      return;
+    }
+
+    compiler.run((error, stats) => {
+      if (error || stats.hasErrors()) {
+        handleStats(error, stats);
+        compiler.close(() => {});
+        return;
+      }
+
+      console.log(
+        stats.toString({
+          colors: true,
+          chunks: false,
+          modules: false,
+        })
+      );
+
+      compiler.close((closeError) => {
+        if (closeError) {
+          reject(closeError);
+          return;
+        }
+
+        resolve();
+      });
+    });
+  });
+}
+
+module.exports = {
+  runWebpack,
+};

package/dist/scripts/cli.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const { runWebpack } = require('./build');
+const { loadConfig } = require('./config-loader');
+const { copyIcons } = require('./icons');
+const { generateInstallerFiles } = require('./install-generator');
+const { initProject } = require('./init');
+
+function printHelp() {
+  console.log(`dazscript <command> [options]
+
+Commands:
+  init                Scaffold a DazScript project in the current directory
+  build               Build DazScript files
+  watch               Build and watch DazScript files
+  icons               Copy png assets into the output directory
+  installer           Generate Install.dsa.ts and Uninstall.dsa.ts
+
+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
+  --force               Overwrite generated files
+  --help                Show this message
+`);
+}
+
+function parseOptions(args, defaults) {
+  const options = { ...defaults };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === '--menu-path') {
+      options.menuPath = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--scripts-path') {
+      options.scriptsPath = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--out-dir') {
+      options.outDir = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--file') {
+      options.file = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return options;
+}
+
+function getResolvedOptions(workdir, cliOptions) {
+  const { config } = loadConfig(workdir);
+
+  const options = {
+    ...config,
+    ...cliOptions,
+  };
+
+  if (!options.menuPath && options.defaultMenuPath) {
+    options.menuPath = options.defaultMenuPath;
+  }
+
+  return options;
+}
+
+async function main(argv) {
+  const [, , command, ...rest] = argv;
+  const workdir = process.cwd();
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  const options = parseOptions(rest, {
+    force: false,
+    menuPath: undefined,
+    scriptsPath: undefined,
+    outDir: undefined,
+    file: undefined,
+  });
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const resolvedOptions = getResolvedOptions(workdir, options);
+  resolvedOptions.menuPath = resolvedOptions.menuPath || '/MyScripts';
+  resolvedOptions.scriptsPath = resolvedOptions.scriptsPath || './src';
+  resolvedOptions.outDir = resolvedOptions.outDir || './out';
+
+  if (command === 'init') {
+    initProject(workdir, resolvedOptions);
+    return;
+  }
+
+  if (command === 'build') {
+    await runWebpack(workdir, resolvedOptions);
+    return;
+  }
+
+  if (command === 'watch') {
+    await runWebpack(workdir, { ...resolvedOptions, watch: true });
+    return;
+  }
+
+  if (command === 'icons') {
+    copyIcons(workdir, resolvedOptions);
+    return;
+  }
+
+  if (command === 'installer') {
+    generateInstallerFiles(workdir, {
+      scriptsPath: resolvedOptions.scriptsPath,
+      defaultMenuPath: resolvedOptions.menuPath,
+    });
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+try {
+  Promise.resolve(main(process.argv)).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/dist/scripts/config-loader.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const ts = require('typescript');
+
+function loadModuleFromString(code, filename) {
+  const module = { exports: {} };
+  const dirname = path.dirname(filename);
+  const localRequire = (request) => {
+    if (request.startsWith('.')) {
+      return require(path.resolve(dirname, request));
+    }
+
+    return require(request);
+  };
+
+  const fn = new Function(
+    'exports',
+    'require',
+    'module',
+    '__filename',
+    '__dirname',
+    code
+  );
+
+  fn(module.exports, localRequire, module, filename, dirname);
+  return module.exports;
+}
+
+function getConfigCandidates(workdir) {
+  return [
+    path.join(workdir, 'dazscript.config.ts'),
+    path.join(workdir, 'dazscript.config.js'),
+    path.join(workdir, 'dazscript.config.cjs'),
+  ];
+}
+
+function loadTsConfig(filePath) {
+  const source = fs.readFileSync(filePath, 'utf8');
+  const transpiled = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2019,
+      esModuleInterop: true,
+    },
+    fileName: filePath,
+  });
+
+  const loaded = loadModuleFromString(transpiled.outputText, filePath);
+  return loaded.default || loaded;
+}
+
+function loadJsConfig(filePath) {
+  const loaded = require(filePath);
+  return loaded.default || loaded;
+}
+
+function loadConfig(workdir) {
+  for (const candidate of getConfigCandidates(workdir)) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+
+    const config = candidate.endsWith('.ts')
+      ? loadTsConfig(candidate)
+      : loadJsConfig(candidate);
+
+    return {
+      config,
+      filePath: candidate,
+    };
+  }
+
+  return {
+    config: {},
+    filePath: null,
+  };
+}
+
+module.exports = {
+  loadConfig,
+};

package/dist/scripts/icons.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+function copyFile(sourcePath, targetPath) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(sourcePath, targetPath);
+  console.log(`copy ${path.relative(process.cwd(), targetPath)}`);
+}
+
+function copyIcons(workdir, options) {
+  const sourceRoot = path.resolve(workdir, 'src');
+  const outDir = path.resolve(workdir, options.outDir || './out');
+  const pattern = path.join(sourceRoot, '**/*.png').replace(/\\/g, '/');
+  const files = glob.sync(pattern);
+
+  files.forEach((filePath) => {
+    const relativePath = path.relative(sourceRoot, filePath);
+    copyFile(filePath, path.join(outDir, relativePath));
+  });
+}
+
+module.exports = {
+  copyIcons,
+};

package/dist/scripts/init.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function normalizePath(value, fallback) {
+  if (!value) {
+    return fallback;
+  }
+
+  return value.replace(/\\/g, '/');
+}
+
+function formatConfigPath(value) {
+  if (value.startsWith('./') || value.startsWith('../') || value.startsWith('/')) {
+    return value;
+  }
+
+  return `./${value}`;
+}
+
+function ensureTrailingSlash(value) {
+  return value.endsWith('/') ? value : `${value}/`;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, json) {
+  fs.writeFileSync(filePath, `${JSON.stringify(json, null, 2)}\n`);
+}
+
+function writeFileIfNeeded(filePath, content, force) {
+  if (fs.existsSync(filePath) && !force) {
+    console.log(`skip ${path.basename(filePath)}`);
+    return false;
+  }
+
+  fs.writeFileSync(filePath, content);
+  console.log(`write ${path.basename(filePath)}`);
+  return true;
+}
+
+function buildConfigContent(options) {
+  return `import { defineConfig } from 'dazscript-framework/config';
+
+export default defineConfig({
+  scriptsPath: '${options.scriptsPath}',
+  outDir: '${options.outDir}',
+  defaultMenuPath: '${options.menuPath}',
+});
+`;
+}
+
+function buildTsconfigContent() {
+  return `{
+  "extends": "./node_modules/dazscript-framework/tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "paths": {
+      "shared/*": ["src/shared/*"],
+      "@dst/*": ["node_modules/dazscript-types/src/types/*"],
+      "@dsf/*": ["node_modules/dazscript-framework/src/*"]
+    }
+  },
+  "include": ["node_modules/dazscript-types/src/types/**/*", "src/**/*"]
+}
+`;
+}
+
+function updatePackageJson(workdir, options) {
+  const packageJsonPath = path.join(workdir, 'package.json');
+  const packageJson = fs.existsSync(packageJsonPath)
+    ? readJson(packageJsonPath)
+    : { private: true };
+
+  if (packageJson.sideEffects === undefined) {
+    packageJson.sideEffects = false;
+  }
+
+  packageJson.scripts = {
+    ...(packageJson.scripts || {}),
+    prebuild: 'npm run installer',
+    build: 'dazscript build',
+    postbuild: 'npm run icons',
+    watch: 'dazscript watch',
+    icons: 'dazscript icons',
+    installer: 'dazscript installer',
+  };
+
+  writeJson(packageJsonPath, packageJson);
+  console.log('update package.json');
+}
+
+function initProject(workdir, rawOptions) {
+  const options = {
+    force: Boolean(rawOptions.force),
+    menuPath: normalizePath(rawOptions.menuPath, '/MyScripts'),
+    scriptsPath: normalizePath(rawOptions.scriptsPath, './src'),
+    outDir: normalizePath(rawOptions.outDir, './out'),
+  };
+
+  writeFileIfNeeded(
+    path.join(workdir, 'dazscript.config.ts'),
+    buildConfigContent(options),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, 'tsconfig.json'),
+    buildTsconfigContent(),
+    options.force
+  );
+
+  updatePackageJson(workdir, options);
+}
+
+module.exports = {
+  initProject,
+};