dazscript-framework 1.0.32 → 1.0.33

package/README.md

@@ -11,6 +11,7 @@
   - [Installation & Setup](#installation--setup)
   - [Unit Tests](#unit-tests)
   - [DAZ Studio Integration Tests](#daz-studio-integration-tests)
+  - [DAZ Studio Headless Probes](#daz-studio-headless-probes)
   - [Project Configuration](#project-configuration)
   - [The `action(...)` Entrypoint](#the-action-entrypoint)
   - [Build Output: Launcher Shims](#build-output-launcher-shims)
@@ -62,6 +63,7 @@ To include optional test scaffolds, run one or both:
 ```bash
 npx dazscript init --unit-tests
 npx dazscript init --integration-tests
+npx dazscript init --probes
 ```
 
 ### 3. Write the script
@@ -177,6 +179,7 @@ Available `init` flags:
 npx dazscript init --menu-path /MyScripts --scripts-path ./src --out-dir ./out --app-data-path YourName/my-project
 npx dazscript init --unit-tests --app-data-path YourName/my-project
 npx dazscript init --integration-tests --app-data-path YourName/my-project
+npx dazscript init --probes --app-data-path YourName/my-project
 ```
 
 | Flag | Description |
@@ -222,6 +225,22 @@ npm run test:integration
 
 The generated script calls `dazscript integration --fixture ./test/integration/fixtures/<project>-smoke.dsa.ts`. Configure local machine paths in an ignored `.env.integration.local`; `DAZ_STUDIO_EXE` is always required, and `DAZ_TEST_CONTENT_DUF` is required only for tests that use `--require-content`. See `test/integration/README.md` in this repository for maintainer and consuming-project details.
 
+### DAZ Studio headless probes
+
+Projects can bootstrap non-asserting DAZ Studio probes with:
+
+```bash
+npx dazscript init --probes
+```
+
+Run a probe with:
+
+```bash
+npm run probe
+```
+
+Probes use the same headless DAZ build and launch infrastructure as integration tests, but they do not require `ok: true` assertions. A probe succeeds when DAZ completes and writes readable JSON. Use `dazscript probe` for exploratory runtime observations such as available globals, installed plugins, scene state, signal behavior, or content loading details.
+
 ---
 
 ### Project Configuration
@@ -592,7 +611,7 @@ my-daz-scripts/
 
 Files ending in `.dsa.ts` are treated as runnable entry points and compiled to `.dsa`. Plain `.ts` files are modules — imported by entry points but not compiled independently.
 
-The `test/unit/` files are generated only when you run `dazscript init --unit-tests`. The `test/integration/` files and env examples are generated only when you run `dazscript init --integration-tests`.
+The `test/unit/` files are generated only when you run `dazscript init --unit-tests`. The `test/integration/` files and env examples are generated only when you run `dazscript init --integration-tests`. The `probes/` files and probe env examples are generated only when you run `dazscript init --probes`.
 
 **Common commands**
 

package/dist/scripts/cli.js

@@ -9,7 +9,7 @@ const { copyIcons } = require('./icons');
 const { runEncrypt } = require('./encrypt');
 const { generateInstallerFiles } = require('./install-generator');
 const { initProject } = require('./init');
-const { runIntegration } = require('./integration');
+const { runIntegration, runProbe } = require('./integration');
 
 function printHelp() {
   console.log(`dazscript <command> [options]
@@ -22,6 +22,7 @@ Commands:
   icons               Copy png assets into the output directory
   installer           Generate Install.dsa.ts and Uninstall.dsa.ts
   integration         Run a DAZ Studio headless integration fixture
+  probe               Run a non-asserting DAZ Studio headless probe fixture
 
 Options:
   --menu-path <path>    Default menu path. Default: /MyScripts
@@ -32,11 +33,12 @@ Options:
   --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
-  --fixture <path>      Integration fixture .dsa.ts file
-  --env-file <path>     Integration env file. Default: .env.integration.local
-  --require-content     Require DAZ_TEST_CONTENT_DUF for integration tests
+  --fixture <path>      Integration or probe fixture .dsa.ts file
+  --env-file <path>     Integration/probe env file. Defaults: .env.integration.local or .env.probe.local
+  --require-content     Require DAZ_TEST_CONTENT_DUF for integration tests or probes
   --unit-tests          Add Vitest unit-test scaffold during init
   --integration-tests   Add integration-test scaffold during init
+  --probes              Add DAZ headless probe scaffold during init
   --force               Overwrite generated files
   --help                Show this message
 `);
@@ -109,6 +111,11 @@ function parseOptions(args, defaults) {
       continue;
     }
 
+    if (arg === '--probes') {
+      options.probes = true;
+      continue;
+    }
+
     if (arg === '--menu-path') {
       options.menuPath = args[index + 1];
       index += 1;
@@ -230,6 +237,7 @@ async function main(argv) {
     requireContent: false,
     unitTests: false,
     integrationTests: false,
+    probes: false,
   });
 
   if (options.help) {
@@ -242,6 +250,11 @@ async function main(argv) {
     return;
   }
 
+  if (command === 'probe') {
+    await runProbe(options, process.env, workdir);
+    return;
+  }
+
   const commandOptions =
     command === 'init'
       ? await resolveInitOptions(workdir, options)

package/dist/scripts/init.js

@@ -147,6 +147,23 @@ function updatePackageJsonForIntegration(workdir, fixturePath) {
   }
 }
 
+function updatePackageJsonForProbe(workdir, fixturePath) {
+  const packageJsonPath = path.join(workdir, 'package.json');
+  const packageJson = fs.existsSync(packageJsonPath)
+    ? readJson(packageJsonPath)
+    : { private: true };
+
+  packageJson.scripts = packageJson.scripts || {};
+  if (packageJson.scripts.probe) {
+    console.log('skip package.json probe');
+  }
+  else {
+    packageJson.scripts.probe = `dazscript probe --fixture ${fixturePath}`;
+    writeJson(packageJsonPath, packageJson);
+    console.log('update package.json');
+  }
+}
+
 function isNpmDefaultTestScript(scriptName, command) {
   return scriptName === 'test' && command === 'echo "Error: no test specified" && exit 1';
 }
@@ -423,6 +440,122 @@ function initIntegrationTests(workdir, options) {
   ensureLine(path.join(workdir, '.gitignore'), '.env.integration.local');
 }
 
+function buildProbeFixtureContent() {
+  return `import { action } from '@dsf/core/action'
+import { saveToFile } from '@dsf/helpers/file-helper'
+import { getStringScriptArguments } from '@dsf/helpers/script-helper'
+
+type ProbeResult = {
+    kind: string
+    status: string
+    observations: Record<string, unknown>
+}
+
+const countSceneNodes = (): number => {
+    return Scene.getNumNodes()
+}
+
+action({ text: 'Scene Probe', menuPath: false }, () => {
+    const args = getStringScriptArguments()
+    const resultPath = args.length > 0 ? args[0] : ''
+    const result: ProbeResult = {
+        kind: 'daz-headless-probe',
+        status: 'observed',
+        observations: {
+            graphicsMode: App.getGraphicsMode(),
+            interfaceAvailable: !!App.getInterface(),
+            nodeCount: countSceneNodes(),
+            time: String(Scene.getTime()),
+            frame: Scene.getFrame()
+        }
+    }
+
+    if (resultPath) {
+        saveToFile(resultPath, JSON.stringify(result, null, 2))
+    }
+})
+`;
+}
+
+function buildProbeReadmeContent(fixturePath) {
+  return `# DAZ Headless Probes
+
+Probes are non-asserting DAZ Studio headless scripts for runtime exploration. They are useful for AI-agent investigations where the desired output is structured observations, not pass/fail test assertions.
+
+Create a local env file:
+
+\`\`\`bash
+cp .env.probe.linux.example .env.probe.local
+\`\`\`
+
+\`\`\`powershell
+Copy-Item .env.probe.windows.example .env.probe.local
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+npm run probe
+\`\`\`
+
+The default scene probe is:
+
+\`\`\`text
+${fixturePath}
+\`\`\`
+
+Generated output is written to \`probes/out/\` and ignored by git.
+`;
+}
+
+function buildProbeLinuxEnvExample() {
+  return `# Copy this file to .env.probe.local and edit paths for your machine.
+# Shell environment variables override values in .env.probe.local.
+# DAZ_STUDIO_EXE is required for probes.
+
+WINEPREFIX=/home/your-user/.local/share/daz-wine/prefix
+DAZ_STUDIO_EXE=/home/your-user/.local/share/daz-wine/prefix/drive_c/Program Files/DAZ 3D/DAZStudio4/DAZStudio.exe
+DAZ_PROBE_TIMEOUT_MS=300000
+`;
+}
+
+function buildProbeWindowsEnvExample() {
+  return `# Copy this file to .env.probe.local and edit paths for your machine.
+# Shell environment variables override values in .env.probe.local.
+# Forward slashes avoid escaping issues in env files.
+# DAZ_STUDIO_EXE is required for probes.
+
+DAZ_STUDIO_EXE=C:/Program Files/DAZ 3D/DAZStudio4/DAZStudio.exe
+DAZ_PROBE_TIMEOUT_MS=300000
+`;
+}
+
+function initProbes(workdir, options) {
+  const fixtureBaseName = `${toFixtureName(path.basename(workdir))}-scene.dsa.ts`;
+  const fixturePath = `./probes/fixtures/${fixtureBaseName}`;
+  const localFixturePath = path.join(workdir, fixturePath);
+
+  writeFileIfNeeded(localFixturePath, buildProbeFixtureContent(), options.force);
+  writeFileIfNeeded(
+    path.join(workdir, 'probes/README.md'),
+    buildProbeReadmeContent(fixturePath),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, '.env.probe.linux.example'),
+    buildProbeLinuxEnvExample(),
+    options.force
+  );
+  writeFileIfNeeded(
+    path.join(workdir, '.env.probe.windows.example'),
+    buildProbeWindowsEnvExample(),
+    options.force
+  );
+  updatePackageJsonForProbe(workdir, fixturePath);
+  ensureLine(path.join(workdir, '.gitignore'), 'probes/out/');
+  ensureLine(path.join(workdir, '.gitignore'), '.env.probe.local');
+}
+
 function initProject(workdir, rawOptions) {
   const projectName = path.basename(workdir);
   const options = {
@@ -434,6 +567,7 @@ function initProject(workdir, rawOptions) {
     bundleName: toBundleName(projectName),
     unitTests: Boolean(rawOptions.unitTests),
     integrationTests: Boolean(rawOptions.integrationTests),
+    probes: Boolean(rawOptions.probes),
   };
 
   writeFileIfNeeded(
@@ -456,10 +590,15 @@ function initProject(workdir, rawOptions) {
   if (options.integrationTests) {
     initIntegrationTests(workdir, options);
   }
+
+  if (options.probes) {
+    initProbes(workdir, options);
+  }
 }
 
 module.exports = {
   initIntegrationTests,
+  initProbes,
   initUnitTests,
   initProject,
 };

package/dist/scripts/integration.js

@@ -71,10 +71,10 @@ function assertRequiredFile(label, filePath, allowDazPath) {
   return resolvedPath;
 }
 
-function resolveIntegrationOptions(cwd, rawOptions, env) {
+function resolveHeadlessOptions(cwd, rawOptions, env, defaults) {
   const options = rawOptions || {};
   const projectRoot = path.resolve(cwd || process.cwd());
-  const envFile = path.resolve(projectRoot, options.envFile || '.env.integration.local');
+  const envFile = path.resolve(projectRoot, options.envFile || defaults.envFile);
   const fixturePath = options.fixture
     ? path.resolve(projectRoot, options.fixture)
     : '';
@@ -100,12 +100,12 @@ function resolveIntegrationOptions(cwd, rawOptions, env) {
     throw new Error(`DAZ_TEST_CONTENT_DUF does not exist: ${path.resolve(rawContentPath)}`);
   }
 
-  const timeoutMs = Number(options.timeoutMs || env.DAZ_TEST_TIMEOUT_MS || defaultTimeoutMs);
+  const timeoutMs = Number(options.timeoutMs || env[defaults.timeoutEnv] || env.DAZ_TEST_TIMEOUT_MS || defaultTimeoutMs);
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new Error(`invalid timeout: ${options.timeoutMs || env.DAZ_TEST_TIMEOUT_MS}`);
+    throw new Error(`invalid timeout: ${options.timeoutMs || env[defaults.timeoutEnv] || env.DAZ_TEST_TIMEOUT_MS}`);
   }
 
-  const outDir = path.resolve(projectRoot, options.outDir || './test/integration/out');
+  const outDir = path.resolve(projectRoot, options.outDir || defaults.outDir);
   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');
@@ -124,12 +124,35 @@ function resolveIntegrationOptions(cwd, rawOptions, env) {
     contentPath: rawContentPath ? normalizeForDaz(rawContentPath) : '',
     requireContent: Boolean(options.requireContent),
     timeoutMs,
-    appDataPath: options.appDataPath || 'DazScriptFramework/integration-tests',
-    bundleName: options.bundleName || 'Integration Test Fixture',
+    appDataPath: options.appDataPath || defaults.appDataPath,
+    bundleName: options.bundleName || defaults.bundleName,
+    commandName: defaults.commandName,
     env,
   };
 }
 
+function resolveIntegrationOptions(cwd, rawOptions, env) {
+  return resolveHeadlessOptions(cwd, rawOptions, env, {
+    commandName: 'integration',
+    envFile: '.env.integration.local',
+    timeoutEnv: 'DAZ_TEST_TIMEOUT_MS',
+    outDir: './test/integration/out',
+    appDataPath: 'DazScriptFramework/integration-tests',
+    bundleName: 'Integration Test Fixture',
+  });
+}
+
+function resolveProbeOptions(cwd, rawOptions, env) {
+  return resolveHeadlessOptions(cwd, rawOptions, env, {
+    commandName: 'probe',
+    envFile: '.env.probe.local',
+    timeoutEnv: 'DAZ_PROBE_TIMEOUT_MS',
+    outDir: './probes/out',
+    appDataPath: 'DazScriptFramework/probes',
+    bundleName: 'Probe Fixture',
+  });
+}
+
 function run(command, args, options) {
   const result = spawnSync(command, args, {
     cwd: options.cwd,
@@ -306,7 +329,7 @@ function runDazFixture(options) {
   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}`);
+  console.log(`[dazscript ${options.commandName || 'integration'}] launching DAZ: ${useWine ? `${command} ${options.dazStudioExe}` : command}`);
   run(command, commandArgs, {
     cwd: options.fixtureRoot,
     env: options.env,
@@ -335,6 +358,19 @@ function readIntegrationResult(resultPath) {
   return result;
 }
 
+function readProbeResult(resultPath) {
+  if (!fs.existsSync(resultPath)) {
+    throw new Error(`DAZ did not write result JSON: ${resultPath}`);
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(resultPath, 'utf8'));
+  }
+  catch (error) {
+    throw new Error(`could not parse result JSON: ${error}`);
+  }
+}
+
 async function runIntegration(rawOptions, injectedEnv, cwd) {
   const env = { ...(injectedEnv || process.env) };
   const projectRoot = path.resolve(cwd || process.cwd());
@@ -349,14 +385,31 @@ async function runIntegration(rawOptions, injectedEnv, cwd) {
   return result;
 }
 
+async function runProbe(rawOptions, injectedEnv, cwd) {
+  const env = { ...(injectedEnv || process.env) };
+  const projectRoot = path.resolve(cwd || process.cwd());
+  const envFile = path.resolve(projectRoot, (rawOptions && rawOptions.envFile) || '.env.probe.local');
+  loadEnvFile(envFile, env);
+
+  const options = resolveProbeOptions(projectRoot, rawOptions, env);
+  buildFixtureProject(options);
+  runDazFixture(options);
+  const result = readProbeResult(options.resultPath);
+  console.log(`[dazscript probe] result: ${options.resultPath}`);
+  return result;
+}
+
 module.exports = {
   loadEnvFile,
   normalizeForDaz,
   getNpmInvocation,
   getFixtureBuildDependencies,
   readIntegrationResult,
+  readProbeResult,
   resolveIntegrationOptions,
+  resolveProbeOptions,
   buildFixtureProject,
   runDazFixture,
   runIntegration,
+  runProbe,
 };

package/package.json

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

package/src/scripts/init.test.ts

@@ -3,7 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 
-const { initIntegrationTests, initUnitTests } = require('../../dist/scripts/init')
+const { initIntegrationTests, initProbes, initUnitTests } = require('../../dist/scripts/init')
 
 const tempDirs: string[] = []
 
@@ -74,6 +74,48 @@ describe('init integration tests', () => {
     })
 })
 
+describe('init probes', () => {
+    it('creates the probe fixture, docs, env examples, npm script, and ignore entries', () => {
+        const projectDir = makeProject('probe-test')
+        const fixtureBaseName = toFixtureName(projectDir)
+
+        initProbes(projectDir, { force: false })
+
+        const fixturePath = path.join(projectDir, `probes/fixtures/${fixtureBaseName}-scene.dsa.ts`)
+        const packageJson = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8'))
+        const gitignore = fs.readFileSync(path.join(projectDir, '.gitignore'), 'utf8')
+
+        expect(fs.existsSync(fixturePath)).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, 'probes/README.md'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, '.env.probe.linux.example'))).toBe(true)
+        expect(fs.existsSync(path.join(projectDir, '.env.probe.windows.example'))).toBe(true)
+        expect(packageJson.scripts.probe).toBe(
+            `dazscript probe --fixture ./probes/fixtures/${fixtureBaseName}-scene.dsa.ts`
+        )
+        expect(gitignore).toContain('probes/out/')
+        expect(gitignore).toContain('.env.probe.local')
+    })
+
+    it('does not replace an existing probe script or duplicate ignore entries', () => {
+        const projectDir = makeProject('existing-probe')
+        const packageJsonPath = path.join(projectDir, 'package.json')
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        packageJson.scripts.probe = 'custom probe'
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2))
+        fs.writeFileSync(path.join(projectDir, '.gitignore'), 'probes/out/\n')
+
+        initProbes(projectDir, { force: false })
+        initProbes(projectDir, { force: false })
+
+        const updatedPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+        const gitignore = fs.readFileSync(path.join(projectDir, '.gitignore'), 'utf8')
+
+        expect(updatedPackageJson.scripts.probe).toBe('custom probe')
+        expect(gitignore.match(/probes\/out\//g)?.length).toBe(1)
+        expect(gitignore.match(/\.env\.probe\.local/g)?.length).toBe(1)
+    })
+})
+
 describe('init unit tests', () => {
     it('creates Vitest config, sample test, docs, npm scripts, and dev dependency', () => {
         const projectDir = makeProject('unit-test')

package/src/scripts/integration.test.ts

@@ -8,7 +8,9 @@ const {
     getFixtureBuildDependencies,
     getNpmInvocation,
     readIntegrationResult,
+    readProbeResult,
     resolveIntegrationOptions,
+    resolveProbeOptions,
 } = require('../../dist/scripts/integration')
 
 const tempDirs: string[] = []
@@ -80,6 +82,28 @@ describe('integration option resolution', () => {
     })
 })
 
+describe('probe option resolution', () => {
+    it('uses probe-specific env and output defaults', () => {
+        const projectDir = makeProject()
+        fs.mkdirSync(path.join(projectDir, 'probes/fixtures'), { recursive: true })
+        fs.writeFileSync(path.join(projectDir, 'probes/fixtures/scene.dsa.ts'), 'action({}, function() {})\n')
+
+        const options = resolveProbeOptions(projectDir, {
+            fixture: './probes/fixtures/scene.dsa.ts',
+        }, {
+            DAZ_STUDIO_EXE: path.join(projectDir, 'DAZStudio.exe'),
+            DAZ_PROBE_TIMEOUT_MS: '123456',
+        })
+
+        expect(options.envFile).toBe(path.join(projectDir, '.env.probe.local'))
+        expect(options.outDir).toBe(path.join(projectDir, 'probes/out'))
+        expect(options.fixtureRoot).toBe(path.join(projectDir, 'probes/out/fixture'))
+        expect(options.resultPath).toBe(path.join(projectDir, 'probes/out/fixture/result.json'))
+        expect(options.timeoutMs).toBe(123456)
+        expect(options.commandName).toBe('probe')
+    })
+})
+
 describe('integration command resolution', () => {
     it('uses node plus npm-cli on Windows so child_process can spawn without a shell', () => {
         const invocation = getNpmInvocation(['--version'], 'win32')
@@ -125,3 +149,21 @@ describe('integration result reader', () => {
         expect(() => readIntegrationResult(resultPath)).toThrow(/bad frame/)
     })
 })
+
+describe('probe result reader', () => {
+    it('accepts arbitrary readable probe JSON without ok assertions', () => {
+        const projectDir = makeProject()
+        const resultPath = path.join(projectDir, 'result.json')
+        fs.writeFileSync(resultPath, JSON.stringify({
+            kind: 'daz-headless-probe',
+            status: 'inconclusive',
+            observations: { interfaceAvailable: false }
+        }))
+
+        expect(readProbeResult(resultPath)).toEqual({
+            kind: 'daz-headless-probe',
+            status: 'inconclusive',
+            observations: { interfaceAvailable: false }
+        })
+    })
+})