Native Mirror Generator

Generate native_*.txtar test files that mirror existing virtual_*.txtar tests using native shell implementations with platform-split CUE.

When to Use

Invoke this skill (/native-mirror) when:

• A new virtual_*.txtar test has been created and needs a native mirror
• An existing virtual test has been modified and its native mirror needs updating
• You want to verify which virtual tests are missing native mirrors

Workflow

Step 1: Check Exemptions

Before generating a mirror, verify the virtual test is NOT exempt:

Source of truth: The machine-enforced exemption list is in tests/cli/runtime_mirror_exemptions.json. This SKILL.md list is a human reference and must stay in sync. TestVirtualRuntimeMirrorCoverage enforces the JSON entries; stale entries cause test failures.

Exempt categories (do NOT create native mirrors):

• virtual_uroot_*.txtar — u-root commands are virtual shell built-ins
• virtual_shell.txtar — Tests virtual-shell-specific features
• virtual_edge_cases.txtar — CUE schema validation, not runtime behavior
• virtual_args_subcommand_conflict.txtar — CUE schema validation
• virtual_diagnostics_footer.txtar — Diagnostics footer output
• container_*.txtar — Linux-only container runtime (outside virtual_* scope)
• dogfooding_invowkfile.txtar — Already exercises native runtime (outside virtual_* scope)
• config_*.txtar, module_*.txtar, completion.txtar, tui_format.txtar, tui_style.txtar, init_*.txtar — Built-in CLI commands, outside virtual_* scope

If the test is exempt, report it and stop.

Step 2: Read the Virtual Test

Read the source virtual_*.txtar file and extract:

1. The test description comments
2. All exec commands and stdout/stderr assertions
3. The embedded invowkfile.cue and any other files
4. Environment variable usage

Step 3: Transform the CUE

Replace each virtual implementation with a platform-split native pair:

From (virtual):

cue
1implementations: [{
2    script: "echo 'Hello'"
3    runtimes: [{name: "virtual"}]
4    platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
5}]

To (native, platform-split):

cue
1implementations: [
2    {
3        script: "echo 'Hello'"
4        runtimes:  [{name: "native"}]
5        platforms: [{name: "linux"}, {name: "macos"}]
6    },
7    {
8        script: "Write-Output 'Hello'"
9        runtimes:  [{name: "native"}]
10        platforms: [{name: "windows"}]
11    },
12]

Step 4: Translate Shell Syntax

Apply these translations for the Windows (PowerShell) implementation:

Step 5: Preserve Assertions

The stdout and stderr assertions must be identical between virtual and native tests. Only the script syntax differs, not the output.

Step 6: Write the Mirror

Create native_<feature>.txtar with:

• Updated description noting it's a native mirror
• Same exec commands and assertions
• Platform-split CUE implementations
• Same embedded support files

Step 7: Verify

bash
1make test-cli

Example

Given virtual_simple.txtar:

txtar
1# Test: Basic hello command
2cd $WORK
3exec invowk cmd hello
4stdout 'Hello from invowk!'
5! stderr .
6
7-- invowkfile.cue --
8cmds: [{
9    name: "hello"
10    description: "Say hello"
11    implementations: [{
12        script: "echo 'Hello from invowk!'"
13        runtimes: [{name: "virtual"}]
14        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
15    }]
16}]

Generate native_simple.txtar:

txtar
1# Test: Basic hello command (native runtime mirror)
2# Native shell mirror of virtual_simple.txtar
3cd $WORK
4exec invowk cmd hello
5stdout 'Hello from invowk!'
6! stderr .
7
8-- invowkfile.cue --
9cmds: [{
10    name: "hello"
11    description: "Say hello"
12    implementations: [
13        {
14            script: "echo 'Hello from invowk!'"
15            runtimes:  [{name: "native"}]
16            platforms: [{name: "linux"}, {name: "macos"}]
17        },
18        {
19            script: "Write-Output 'Hello from invowk!'"
20            runtimes:  [{name: "native"}]
21            platforms: [{name: "windows"}]
22        },
23    ]
24}]

Audit Mode

To check for missing native mirrors, run:

bash
1# List virtual tests
2ls tests/cli/testdata/virtual_*.txtar
3
4# List native tests
5ls tests/cli/testdata/native_*.txtar
6
7# Compare (accounting for exemptions)

Report which virtual tests are missing their native mirrors, excluding exempt files.