dazscript-framework 0.2.3 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # DazScript Framework
 
-> ⚠️ **EARLY VERSION** — This framework is in active development (v0.1.15). The API is not yet stable and may change between releases. Not recommended for production use until v1.0 is released.
+> ⚠️ This framework is under active development. The API may still evolve between releases. If you need a stable long-term surface, wait for `v1.0`.
 
 The **DazScript Framework** is a TypeScript-based framework for writing Daz Studio scripts. It provides all the advantages of a typed language such as autocompletion, error checking, and method parameter documentation and hinting. The framework also includes a set of dialog helpers for rapid UI development.
 
@@ -46,7 +46,7 @@ You can customize the generated defaults:
 npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out
 ```
 
-- `--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`.
+- `--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.
 
@@ -60,42 +60,45 @@ Create a simple script that logs to the console:
 
 ```typescript
 import { debug } from '@dsf/common/log';
-import { action } from '@dsf/core/action-decorator';
-import { BaseScript } from '@dsf/core/base-script';
+import { action } from '@dsf/core/action';
 import { info } from '@dsf/helpers/message-box-helper';
 
-@action({ text: 'Hello World' })
-class HelloWorldScript extends BaseScript {
-    protected run(): void {
-        debug('Hello World!');
-        info('Hello World!');
-    }
-}
-
-new HelloWorldScript().exec();
+action({ text: 'Hello World' }, () => {
+    debug('Hello World!');
+    info('Hello World!');
+});
 ```
 
-### The `@action` Decorator
+### The `action(...)` Entrypoint
 
-Use `@action(...)` on a script class to register how it should appear in Daz Studio.
+Use `action(...)` at module scope to define how a runnable `.dsa.ts` file should appear in Daz Studio and what it should execute.
 
 ```typescript
-@action({
+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!');
+});
+```
+
+`action(...)` also accepts a reusable class with a `run()` method:
+
+```typescript
+class HelloWorldScript {
+    run(): void {
         info('Hello World!');
     }
 }
+
+action({ text: 'Hello World' }, HelloWorldScript);
 ```
 
-Common `@action(...)` parameters:
+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.
@@ -153,14 +156,11 @@ export class MyDialog extends BasicDialog {
 #### 3. Connect & Use in Your Script
 
 ```typescript
-import { action } from '@dsf/core/action-decorator';
-import { BaseScript } from '@dsf/core/base-script';
+import { action } from '@dsf/core/action';
 import { getSelectedNode } from '@dsf/helpers/scene-helper';
 import { MyDialog, MyDialogModel } from './my-dialog';
 
-@action({ text: 'My Dialog Script' })
-class MyDialogScript extends BaseScript {
-    protected run(): void {
+action({ text: 'My Dialog Script' }, () => {
         const model = new MyDialogModel();
         const selectedNode = getSelectedNode();
 
@@ -185,10 +185,7 @@ class MyDialogScript extends BaseScript {
         } else {
             console.log('Dialog cancelled');
         }
-    }
-}
-
-new MyDialogScript().exec();
+});
 ```
 
 ### Core Concepts
@@ -325,15 +322,15 @@ This project uses **semantic-release** for automatic versioning and npm publishi
 
 Use conventional commit messages to control version bumping:
 
-- **`fix: description`** → Patch version bump (0.1.15 → 0.1.16)
+- **`fix: description`** → Patch version bump (`x.y.z` → `x.y.(z+1)`)
   - Bug fixes, patches, or minor improvements
   - Example: `fix: resolve dialog builder layout issue`
 
-- **`feat: description`** → Minor version bump (0.1.15 → 0.2.0)
+- **`feat: description`** → Minor version bump (`x.y.z` → `x.(y+1).0`)
   - New features or significant enhancements
   - Example: `feat: add tree view builder component`
 
-- **`BREAKING CHANGE: description`** → Major version bump (0.1.15 → 1.0.0)
+- **`BREAKING CHANGE: description`** → Major version bump (`x.y.z` → `(x+1).0.0`)
   - Add to commit body for breaking changes
   - Example: `feat: refactor action decorator API\n\nBREAKING CHANGE: action() now requires explicit menu path`
 

package/dist/scripts/install-generator.js

@@ -1,9 +1,9 @@
-const tsFileParser = require('ts-file-parser');
+const ts = require('typescript');
 const fs = require('fs');
 const path = require('path');
 const glob = require('glob');
 
-const nameofActionDecorator = 'action';
+const nameofActionFunction = 'action';
 
 function getPartialPath(filePath) {
   const fileInfo = path.parse(filePath);
@@ -35,95 +35,192 @@ uninstall(${data});
 `;
 }
 
-function processScript(filePath, container, defaultMenuPath) {
-  const fileInfo = path.parse(filePath);
-  const content = fs.readFileSync(filePath, 'utf-8').toString();
-  const json = tsFileParser.parseStruct(content, {}, filePath);
+function literalValue(node) {
+  if (!node) {
+    return undefined;
+  }
 
-  json.classes.forEach((cls) => {
-    const actionDecorator = cls.decorators.find(
-      (d) => d.name === nameofActionDecorator
-    );
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+
+  if (node.kind === ts.SyntaxKind.TrueKeyword) {
+    return true;
+  }
+
+  if (node.kind === ts.SyntaxKind.FalseKeyword) {
+    return false;
+  }
+
+  if (ts.isNumericLiteral(node)) {
+    return Number(node.text);
+  }
 
-    if (!actionDecorator) return;
-
-    const decorator = actionDecorator.arguments[0] ?? {};
-
-    const script = {
-      name: null,
-      text: fileInfo.name.replace('.dsa', ''),
-      filePath:
-        decorator.bundle === undefined
-          ? getPartialPath(filePath)
-          : fileInfo.name.replace('.ts', ''),
-      menuPath: (() => {
-        const relativeDir = path.parse(getPartialPath(filePath)).dir;
-        return relativeDir && relativeDir !== '.'
-          ? `${defaultMenuPath}${relativeDir}`
-          : defaultMenuPath.replace(/\/$/, '');
-      })(),
-      description: fileInfo.name.replace('.dsa', ''),
-      group: stringOrDefault(decorator.group, undefined),
-      shortcut: stringOrDefault(decorator.shortcut),
-      toolbar: stringOrDefault(decorator.toolbar, undefined),
-    };
-
-    const icon = filePath.replace('.ts', '.png');
-    if (fs.existsSync(icon)) {
-      script.icon =
-        decorator.bundle === undefined
-          ? `${getPartialPath(filePath)}.png`
-          : fileInfo.name.replace('.dsa', '.dsa.png');
+  if (ts.isPrefixUnaryExpression(node) && ts.isNumericLiteral(node.operand)) {
+    if (node.operator === ts.SyntaxKind.MinusToken) {
+      return -Number(node.operand.text);
     }
 
-    if (actionDecorator) {
-      script.text = stringOrDefault(decorator.text, script.text);
-      if (typeof decorator.menuPath === 'boolean') {
-        script.menuPath = decorator.menuPath === true ? script.menuPath : '';
-      } else {
-        script.menuPath = stringOrDefault(decorator.menuPath, script.menuPath);
-      }
-      script.menuPath = script.menuPath.replace(
-        '#{defaultMenuPath}',
-        defaultMenuPath
-      );
-      script.shortcut = decorator.shortcut;
+    if (node.operator === ts.SyntaxKind.PlusToken) {
+      return Number(node.operand.text);
     }
+  }
+
+  return undefined;
+}
+
+function objectLiteralToObject(node) {
+  if (!node || !ts.isObjectLiteralExpression(node)) {
+    return null;
+  }
+
+  const result = {};
 
-    console.log(`Adding script: ${script.text}`, script);
-    container.scripts.push(script);
-
-    // Check if the decorator has a "bundle" property
-    if (decorator.bundle !== undefined) {
-      let packageInstallerFilePath = `Install.dsa.ts`;
-      let packageUninstallerFilePath = `Uninstall.dsa.ts`;
-
-      if (decorator.bundle !== true) {
-        // If decorator.bundle is a string, use it as the bundle file name
-        packageInstallerFilePath = `Install ${decorator.bundle}.dsa.ts`;
-        packageUninstallerFilePath = `Uninstall ${decorator.bundle}.dsa.ts`;
-      }
-
-      // Generate a separate file with the specified or default name
-      let bundleScriptContent = generateInstallerTemplate(
-        JSON.stringify(container.scripts, null, 4)
-      );
-      let bundleScriptFilePath = path.join(
-        path.parse(filePath).dir,
-        packageInstallerFilePath
-      );
-      fs.writeFileSync(bundleScriptFilePath, bundleScriptContent);
-
-      bundleScriptContent = generateUninstallerTemplate(
-        JSON.stringify(container.scripts, null, 4)
-      );
-      bundleScriptFilePath = path.join(
-        path.parse(filePath).dir,
-        packageUninstallerFilePath
-      );
-      fs.writeFileSync(bundleScriptFilePath, bundleScriptContent);
+  node.properties.forEach((property) => {
+    if (!ts.isPropertyAssignment(property)) {
+      return;
+    }
+
+    const name = ts.isIdentifier(property.name)
+      ? property.name.text
+      : ts.isStringLiteral(property.name)
+        ? property.name.text
+        : null;
+
+    if (!name) {
+      return;
+    }
+
+    const value = literalValue(property.initializer);
+    if (value !== undefined) {
+      result[name] = value;
     }
   });
+
+  return result;
+}
+
+function getCallName(expression) {
+  if (ts.isIdentifier(expression)) {
+    return expression.text;
+  }
+
+  if (ts.isPropertyAccessExpression(expression)) {
+    return expression.name.text;
+  }
+
+  return null;
+}
+
+function findTopLevelActionCall(content, filePath) {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExpressionStatement(statement)) {
+      continue;
+    }
+
+    const expression = statement.expression;
+    if (!ts.isCallExpression(expression)) {
+      continue;
+    }
+
+    if (getCallName(expression.expression) !== nameofActionFunction) {
+      continue;
+    }
+
+    return expression;
+  }
+
+  return null;
+}
+
+function processScript(filePath, container, defaultMenuPath) {
+  const fileInfo = path.parse(filePath);
+  const content = fs.readFileSync(filePath, 'utf-8').toString();
+  const actionCall = findTopLevelActionCall(content, filePath);
+
+  if (!actionCall) {
+    return;
+  }
+
+  const decorator = objectLiteralToObject(actionCall.arguments[0]) ?? {};
+
+  const script = {
+    name: null,
+    text: fileInfo.name.replace('.dsa', ''),
+    filePath:
+      decorator.bundle === undefined
+        ? getPartialPath(filePath)
+        : fileInfo.name.replace('.ts', ''),
+    menuPath: (() => {
+      const relativeDir = path.parse(getPartialPath(filePath)).dir;
+      return relativeDir && relativeDir !== '.'
+        ? `${defaultMenuPath}${relativeDir}`
+        : defaultMenuPath.replace(/\/$/, '');
+    })(),
+    description: fileInfo.name.replace('.dsa', ''),
+    group: stringOrDefault(decorator.group, undefined),
+    shortcut: stringOrDefault(decorator.shortcut),
+    toolbar: stringOrDefault(decorator.toolbar, undefined),
+  };
+
+  const icon = filePath.replace('.ts', '.png');
+  if (fs.existsSync(icon)) {
+    script.icon =
+      decorator.bundle === undefined
+        ? `${getPartialPath(filePath)}.png`
+        : fileInfo.name.replace('.dsa', '.dsa.png');
+  }
+
+  script.text = stringOrDefault(decorator.text, script.text);
+  if (typeof decorator.menuPath === 'boolean') {
+    script.menuPath = decorator.menuPath === true ? script.menuPath : '';
+  } else {
+    script.menuPath = stringOrDefault(decorator.menuPath, script.menuPath);
+  }
+  script.menuPath = script.menuPath.replace(
+    '#{defaultMenuPath}',
+    defaultMenuPath
+  );
+  script.shortcut = decorator.shortcut;
+
+  console.log(`Adding script: ${script.text}`, script);
+  container.scripts.push(script);
+
+  if (decorator.bundle !== undefined) {
+    let packageInstallerFilePath = `Install.dsa.ts`;
+    let packageUninstallerFilePath = `Uninstall.dsa.ts`;
+
+    if (decorator.bundle !== true) {
+      packageInstallerFilePath = `Install ${decorator.bundle}.dsa.ts`;
+      packageUninstallerFilePath = `Uninstall ${decorator.bundle}.dsa.ts`;
+    }
+
+    let bundleScriptContent = generateInstallerTemplate(
+      JSON.stringify(container.scripts, null, 4)
+    );
+    let bundleScriptFilePath = path.join(
+      path.parse(filePath).dir,
+      packageInstallerFilePath
+    );
+    fs.writeFileSync(bundleScriptFilePath, bundleScriptContent);
+
+    bundleScriptContent = generateUninstallerTemplate(
+      JSON.stringify(container.scripts, null, 4)
+    );
+    bundleScriptFilePath = path.join(
+      path.parse(filePath).dir,
+      packageUninstallerFilePath
+    );
+    fs.writeFileSync(bundleScriptFilePath, bundleScriptContent);
+  }
 }
 
 function processScripts(paths, container, defaultMenuPath) {

package/package.json

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

package/src/core/action-decorator.ts

@@ -1,16 +1 @@
-class CustomActionDefinition {
-    text?: string
-    description?: string
-    icon?: string
-    menuPath?: string | boolean
-    toolbar?: string
-    sort?: number
-    group?: string
-    shortcut?: string
-    bundle?: string | boolean
-}
-
-export const action = (action?: CustomActionDefinition) => {
-    return (target: Function) => {
-    }
-}
+export { ActionDefinition, action } from './action';

package/src/core/action.ts

@@ -0,0 +1,71 @@
+import { debug, error, raise } from '@dsf/common/log';
+
+export class ActionDefinition {
+    text?: string
+    description?: string
+    icon?: string
+    menuPath?: string | boolean
+    toolbar?: string
+    sort?: number
+    group?: string
+    shortcut?: string
+    bundle?: string | boolean
+}
+
+type ActionCallback = () => void
+type ActionRunnable = { [key: string]: unknown }
+type ActionConstructor = new (...args: any[]) => any
+type ActionTarget = ActionCallback | ActionRunnable | ActionConstructor
+
+const isFunction = (value: unknown): value is Function => typeof value === 'function'
+
+const isConstructorTarget = (target: ActionTarget): target is ActionConstructor => {
+    if (!isFunction(target)) {
+        return false
+    }
+
+    const prototype = (target as ActionConstructor).prototype as ActionRunnable | undefined
+    return !!prototype && (typeof prototype.run === 'function' || typeof prototype.exec === 'function')
+}
+
+const invokeRunnable = (target: ActionRunnable) => {
+    if (typeof target.run === 'function') {
+        target.run()
+        return
+    }
+
+    if (typeof target.exec === 'function') {
+        target.exec()
+        return
+    }
+
+    throw new Error('Action target must expose run() or exec().')
+}
+
+export function action(definition: ActionDefinition, target: ActionTarget): void {
+    const scriptName = definition?.text || 'Unnamed Script'
+
+    try {
+        const runnable = isConstructorTarget(target)
+            ? new target()
+            : target
+
+        const announceExecution = !isFunction(runnable) && runnable.anounceExecution === false
+            ? false
+            : true
+
+        if (announceExecution) {
+            debug(`=== Running script "${scriptName}" ===`)
+        }
+
+        if (isFunction(runnable)) {
+            runnable()
+            return
+        }
+
+        invokeRunnable(runnable)
+    } catch (err) {
+        error(`There was an error while running the script "${scriptName}"`)
+        raise(err)
+    }
+}

package/src/samples/hello-world.dsa.ts

@@ -1,13 +1,8 @@
 import { debug } from '@dsf/common/log';
-import { action } from '@dsf/core/action-decorator';
-import { BaseScript } from '@dsf/core/base-script';
+import { action } from '@dsf/core/action';
 import { info } from '@dsf/helpers/message-box-helper';
 
-@action({ text: 'Hello World' })
-class HelloWorldScript extends BaseScript {
-    protected run(): void {
-        debug('Hello World!');
-        info('Hello World!');
-    }
-}
-new HelloWorldScript().exec();
+action({ text: 'Hello World' }, () => {
+    debug('Hello World!');
+    info('Hello World!');
+})

package/src/samples/sample-dialog.dsa.ts

@@ -1,52 +1,47 @@
 import { debug, dump } from '@dsf/common/log';
-import { action } from '@dsf/core/action-decorator';
-import { BaseScript } from '@dsf/core/base-script';
+import { action } from '@dsf/core/action';
 import { error } from '@dsf/helpers/message-box-helper';
 import { getNodes, getSelectedNode } from '@dsf/helpers/scene-helper';
 import { SampleDialog, SampleDialogModel } from './sample-dialog';
 
-@action({ text: 'Sample Dialog' })
-class SampleDialogScript extends BaseScript {
-    protected run(): void {
-        let sceneNodes = getNodes()
-        let selectedNode = getSelectedNode()
-        if (!selectedNode) {
-            error('Please select a node.')
-            return
-        }
-
-        let model = new SampleDialogModel()
-        model.nodes$.value = sceneNodes
-
-        model.nodeLabel$.connect((label) => {
-            if (label === model.selectedNode$.value.getLabel()) return
-            model.selectedNode$.value.setLabel(label)
-            model.nodes$.value = getNodes()
-        })
-
-        let dialog = new SampleDialog(model)
-
-        model.selectedNode$.connect((node) => {
-            if (!node) return
-            debug(`Selected Node: ${node.getLabel()}`)
-            node.select(true)
-            model.nodeLabel$.value = node.getLabel()
-            model.showNode$.value = node.isVisible()
-            model.hideNode$.value = !node.isVisible()
-        })
-        dialog.onNodeVisibilityChanged = (node, visible) => {
-            node.setVisible(visible)
-        }
-
-        model.selectedNode$.value = selectedNode
-
-        if (!dialog.run()) {
-            debug(`Dialog Cancelled`)
-            return
-        }
-
-        debug(`Dialog Closed`)
-        dump(model)
+action({ text: 'Sample Dialog' }, () => {
+    let sceneNodes = getNodes()
+    let selectedNode = getSelectedNode()
+    if (!selectedNode) {
+        error('Please select a node.')
+        return
     }
-}
-new SampleDialogScript().exec();
+
+    let model = new SampleDialogModel()
+    model.nodes$.value = sceneNodes
+
+    model.nodeLabel$.connect((label) => {
+        if (label === model.selectedNode$.value.getLabel()) return
+        model.selectedNode$.value.setLabel(label)
+        model.nodes$.value = getNodes()
+    })
+
+    let dialog = new SampleDialog(model)
+
+    model.selectedNode$.connect((node) => {
+        if (!node) return
+        debug(`Selected Node: ${node.getLabel()}`)
+        node.select(true)
+        model.nodeLabel$.value = node.getLabel()
+        model.showNode$.value = node.isVisible()
+        model.hideNode$.value = !node.isVisible()
+    })
+    dialog.onNodeVisibilityChanged = (node, visible) => {
+        node.setVisible(visible)
+    }
+
+    model.selectedNode$.value = selectedNode
+
+    if (!dialog.run()) {
+        debug(`Dialog Cancelled`)
+        return
+    }
+
+    debug(`Dialog Closed`)
+    dump(model)
+})