dazscript-framework 1.0.32 → 1.0.34

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.34",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",

package/src/helpers/skeleton-helper.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import { getMirrorNameCandidate, getMirrorNodeMatch, getMirrorNodes } from './skeleton-helper'
+
+type TestNode = {
+    name: string
+    getName: () => string
+}
+
+const node = (name: string): TestNode => ({
+    name,
+    getName: () => name
+})
+
+const figure = (names: string[]) => ({
+    findNodeChild: (name: string) => names.indexOf(name) >= 0 ? node(name) : null
+})
+
+describe('skeleton mirror helper', () => {
+    it('resolves Genesis-style compact prefixes', () => {
+        expect(getMirrorNameCandidate('rThighBend')).toMatchObject({
+            side: 'right',
+            convention: 'compact-prefix',
+            sourceToken: 'r',
+            mirrorToken: 'l',
+            mirrorName: 'lThighBend'
+        })
+
+        expect(getMirrorNameCandidate('lHand')).toMatchObject({
+            side: 'left',
+            mirrorName: 'rHand'
+        })
+    })
+
+    it('resolves underscore prefix and suffix names', () => {
+        expect(getMirrorNameCandidate('right_hand')).toMatchObject({
+            side: 'right',
+            convention: 'underscore-prefix',
+            mirrorName: 'left_hand'
+        })
+
+        expect(getMirrorNameCandidate('hand_R')).toMatchObject({
+            side: 'right',
+            convention: 'underscore-suffix',
+            mirrorName: 'hand_L'
+        })
+    })
+
+    it('resolves word prefix and suffix names', () => {
+        expect(getMirrorNameCandidate('RightHand')).toMatchObject({
+            side: 'right',
+            convention: 'word-prefix',
+            mirrorName: 'LeftHand'
+        })
+
+        expect(getMirrorNameCandidate('HandLeft')).toMatchObject({
+            side: 'left',
+            convention: 'word-suffix',
+            mirrorName: 'HandRight'
+        })
+    })
+
+    it('does not classify center bones as mirrored', () => {
+        expect(getMirrorNameCandidate('hip')).toBeNull()
+        expect(getMirrorNameCandidate('abdomenLower')).toBeNull()
+    })
+
+    it('returns rich match metadata while keeping getMirrorNodes compatible', () => {
+        const testFigure = figure(['lThighBend', 'hip'])
+        const source = node('rThighBend')
+        const center = node('hip')
+
+        const match = getMirrorNodeMatch(testFigure as unknown as DzSkeleton, source as unknown as DzNode)
+
+        expect(match.side).toBe('right')
+        expect(match.mirror?.getName()).toBe('lThighBend')
+        expect(getMirrorNodes(testFigure as unknown as DzSkeleton, [
+            source as unknown as DzNode,
+            center as unknown as DzNode
+        ]).map(item => item.getName())).toEqual(['lThighBend'])
+    })
+})

package/src/helpers/skeleton-helper.ts

@@ -10,18 +10,143 @@ export const getModifiers = (figure: DzSkeleton): DzModifier[] => {
     return modifiers
 }
 
+export type MirrorSide = 'left' | 'right'
+
+export type MirrorNameConvention =
+    | 'compact-prefix'
+    | 'underscore-prefix'
+    | 'underscore-suffix'
+    | 'word-prefix'
+    | 'word-suffix'
+
+export type MirrorNodeMatch = {
+    source: DzNode
+    mirror: DzNode | null
+    side: MirrorSide | null
+    convention: MirrorNameConvention | null
+    sourceToken: string | null
+    mirrorToken: string | null
+    mirrorName: string | null
+}
+
+type MirrorNameCandidate = Omit<MirrorNodeMatch, 'source' | 'mirror'>
+
+const preserveCase = (source: string, replacement: string): string => {
+    if (source.toUpperCase() === source) return replacement.toUpperCase()
+    if (source.toLowerCase() === source) return replacement.toLowerCase()
+    if (source.length > 0 && source[0].toUpperCase() === source[0]) {
+        return replacement[0].toUpperCase() + replacement.substring(1).toLowerCase()
+    }
+
+    return replacement
+}
+
+export const getMirrorNameCandidate = (name: string): MirrorNameCandidate | null => {
+    const compactPrefix = /^([lr])([A-Z].*)$/.exec(name)
+    if (compactPrefix) {
+        const sourceToken = compactPrefix[1]
+        const mirrorToken = sourceToken === 'r' ? 'l' : 'r'
+        return {
+            side: sourceToken === 'r' ? 'right' : 'left',
+            convention: 'compact-prefix',
+            sourceToken,
+            mirrorToken,
+            mirrorName: `${mirrorToken}${compactPrefix[2]}`
+        }
+    }
+
+    const underscorePrefix = /^(r|l|right|left)([_-].+)$/i.exec(name)
+    if (underscorePrefix) {
+        const sourceToken = underscorePrefix[1]
+        const side = sourceToken.toLowerCase()[0] === 'r' ? 'right' : 'left'
+        const mirrorToken = preserveCase(sourceToken, sourceToken.length === 1
+            ? (side === 'right' ? 'l' : 'r')
+            : (side === 'right' ? 'left' : 'right'))
+        return {
+            side,
+            convention: 'underscore-prefix',
+            sourceToken,
+            mirrorToken,
+            mirrorName: `${mirrorToken}${underscorePrefix[2]}`
+        }
+    }
+
+    const underscoreSuffix = /^(.+[_-])(r|l|right|left)$/i.exec(name)
+    if (underscoreSuffix) {
+        const sourceToken = underscoreSuffix[2]
+        const side = sourceToken.toLowerCase()[0] === 'r' ? 'right' : 'left'
+        const mirrorToken = preserveCase(sourceToken, sourceToken.length === 1
+            ? (side === 'right' ? 'l' : 'r')
+            : (side === 'right' ? 'left' : 'right'))
+        return {
+            side,
+            convention: 'underscore-suffix',
+            sourceToken,
+            mirrorToken,
+            mirrorName: `${underscoreSuffix[1]}${mirrorToken}`
+        }
+    }
+
+    const wordPrefix = /^(right|left)([A-Z].*)$/i.exec(name)
+    if (wordPrefix) {
+        const sourceToken = wordPrefix[1]
+        const side = sourceToken.toLowerCase() === 'right' ? 'right' : 'left'
+        const mirrorToken = preserveCase(sourceToken, side === 'right' ? 'left' : 'right')
+        return {
+            side,
+            convention: 'word-prefix',
+            sourceToken,
+            mirrorToken,
+            mirrorName: `${mirrorToken}${wordPrefix[2]}`
+        }
+    }
+
+    const wordSuffix = /^(.+[a-z])(Right|Left)$/i.exec(name)
+    if (wordSuffix) {
+        const sourceToken = wordSuffix[2]
+        const side = sourceToken.toLowerCase() === 'right' ? 'right' : 'left'
+        const mirrorToken = preserveCase(sourceToken, side === 'right' ? 'left' : 'right')
+        return {
+            side,
+            convention: 'word-suffix',
+            sourceToken,
+            mirrorToken,
+            mirrorName: `${wordSuffix[1]}${mirrorToken}`
+        }
+    }
+
+    return null
+}
+
+export const getMirrorNodeMatch = (figure: DzSkeleton, node: DzNode): MirrorNodeMatch => {
+    const name = node.getName().valueOf()
+    const candidate = getMirrorNameCandidate(name)
+
+    if (!candidate) {
+        return {
+            source: node,
+            mirror: null,
+            side: null,
+            convention: null,
+            sourceToken: null,
+            mirrorToken: null,
+            mirrorName: null
+        }
+    }
+
+    return {
+        source: node,
+        mirror: figure.findNodeChild(candidate.mirrorName, true),
+        ...candidate
+    }
+}
+
+export const getMirrorNodeMatches = (figure: DzSkeleton, nodes: DzNode[]): MirrorNodeMatch[] => {
+    return nodes.map(node => getMirrorNodeMatch(figure, node))
+}
+
 export const getMirrorNodes = (figure: DzSkeleton, nodes: DzNode[]): DzNode[] => {
-    let mirrorNodes: DzNode[] = []
-
-    nodes.forEach((node) => {
-        const name = node.getName().valueOf()
-        let prefix = name[0]
-        if (prefix !== 'r' && prefix !== 'l') return
-        prefix = prefix === 'r' ? 'l' : 'r'
-        const mirrorName = `${prefix}${name.substring(1)}`
-        const mirrorNode = figure.findNodeChild(mirrorName, true)
-        if (mirrorNode) mirrorNodes.push(mirrorNode)
-    })
-
-    return mirrorNodes
-}
+    return getMirrorNodeMatches(figure, nodes)
+        .map(match => match.mirror)
+        .filter(node => node !== null) as DzNode[]
+}

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 }
+        })
+    })
+})