@untestutils/cli 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 s00d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const result = spawnSync(
+  process.execPath,
+  ['--import', 'tsx', join(here, 'src/run.ts'), ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@untestutils/cli",
+  "version": "0.5.0",
+  "description": "CLI for untestutils: init, convert, ai, doctor, and monorepo commands",
+  "license": "MIT",
+  "homepage": "https://s00d.github.io/untestutils/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/s00d/untestutils.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "untestutils": "./bin.mjs"
+  },
+  "files": [
+    "src",
+    "bin.mjs",
+    "templates"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/main.ts",
+  "types": "./src/main.ts",
+  "exports": {
+    ".": {
+      "types": "./src/main.ts",
+      "import": "./src/main.ts",
+      "default": "./src/main.ts"
+    },
+    "./bin.mjs": "./bin.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "consola": "^3.4.2",
+    "nypm": "^0.6.10",
+    "pathe": "^2.0.3",
+    "tinyglobby": "^0.2.17",
+    "tsx": "^4.23.13",
+    "@untestutils/ai": "0.5.0",
+    "@untestutils/core": "0.5.0",
+    "@untestutils/perf": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.1",
+    "publint": "^0.3.24",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "cli": "tsx ./src/run.ts",
+    "build": "node -e \"console.log('[@untestutils/cli] src+tsx — no emit')\"",
+    "publint": "publint --strict"
+  }
+}

package/src/commands/ai.ts

@@ -0,0 +1,90 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { resolve } from 'pathe';
+import { aiTest, aiTestFromFile } from '@untestutils/ai';
+import { writeText } from '../utils/fs';
+
+export const aiCommand = defineCommand({
+  meta: {
+    name: 'ai',
+    alias: ['generate'],
+    description: 'Generate an e2e test from a prompt or markdown file',
+  },
+  args: {
+    prompt: {
+      type: 'string',
+      description: 'Scenario text',
+      alias: 'p',
+    },
+    file: {
+      type: 'string',
+      description: 'Markdown with frontmatter (id/root/recipes/focus)',
+      alias: 'f',
+    },
+    id: {
+      type: 'string',
+      description: 'Generation id',
+      default: 'cli',
+    },
+    root: {
+      type: 'string',
+      description: 'Project root',
+      default: '.',
+    },
+    recipes: {
+      type: 'string',
+      description: 'Comma-separated recipe ids',
+      default: '',
+    },
+    focus: {
+      type: 'string',
+      description: 'Comma-separated focus file hints',
+      default: '',
+    },
+    out: {
+      type: 'string',
+      description: 'Copy generated file to this path',
+    },
+  },
+  async run({ args }) {
+    const root = resolve(String(args.root));
+    const recipes = String(args.recipes || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const focus = String(args.focus || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    let result;
+    if (args.file) {
+      consola.start(`AI from file ${args.file}`);
+      result = await aiTestFromFile(resolve(String(args.file)), {
+        id: String(args.id),
+        root,
+        recipes,
+        focus,
+      });
+    } else if (args.prompt) {
+      consola.start('AI generation from prompt');
+      result = await aiTest({
+        id: String(args.id),
+        prompt: String(args.prompt),
+        root,
+        recipes,
+        focus,
+      });
+    } else {
+      consola.error('Provide --prompt or --file');
+      process.exitCode = 1;
+      return;
+    }
+
+    consola.success(`Generated: ${result.genPath}`);
+    if (args.out) {
+      await writeText(resolve(String(args.out)), result.code);
+      consola.success(`Copied to ${args.out}`);
+    }
+  },
+});

package/src/commands/convert.ts

@@ -0,0 +1,58 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { resolve, dirname, basename, join } from 'pathe';
+import { convertTestFile } from '@untestutils/ai';
+import { writeText, pathExists } from '../utils/fs';
+import { copyFile } from 'node:fs/promises';
+
+export const convertCommand = defineCommand({
+  meta: {
+    name: 'convert',
+    description: 'Convert existing tests to the untestutils API via AI',
+  },
+  args: {
+    path: {
+      type: 'positional',
+      description: 'Test file path',
+      required: true,
+    },
+    'in-place': {
+      type: 'boolean',
+      description: 'Overwrite source (writes .bak backup)',
+      default: false,
+      alias: 'i',
+    },
+    root: {
+      type: 'string',
+      description: 'Project root for AI tools',
+      default: '.',
+    },
+  },
+  async run({ args }) {
+    const file = resolve(String(args.path));
+    if (!(await pathExists(file))) {
+      consola.error(`File not found: ${file}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    consola.start(`Converting ${file}`);
+    const result = await convertTestFile({
+      path: file,
+      root: resolve(String(args.root)),
+    });
+
+    if (args['in-place']) {
+      const bak = `${file}.bak`;
+      await copyFile(file, bak);
+      await writeText(file, result.code);
+      consola.success(`Overwrote ${file} (backup: ${bak})`);
+    } else {
+      const dir = dirname(file);
+      const base = basename(file).replace(/(\.test|\.spec)?(\.[cm]?[jt]sx?)$/, '');
+      const out = join(dir, `${base}.untestutils.test.ts`);
+      await writeText(out, result.code);
+      consola.success(`Wrote ${out}`);
+    }
+  },
+});

package/src/commands/cover.ts

@@ -0,0 +1,74 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { resolve } from 'pathe';
+import { coverMissingTests } from '@untestutils/ai';
+
+export const coverCommand = defineCommand({
+  meta: {
+    name: 'cover',
+    alias: ['write-tests'],
+    description: 'Write missing e2e tests via AI (explores recipes/pages; optional browser)',
+  },
+  args: {
+    root: {
+      type: 'string',
+      description: 'Project root',
+      default: '.',
+    },
+    recipes: {
+      type: 'string',
+      description: 'Comma-separated recipe ids',
+      default: '',
+    },
+    focus: {
+      type: 'string',
+      description: 'Comma-separated focus paths',
+      default: '',
+    },
+    'base-url': {
+      type: 'string',
+      description: 'Live app URL for browser_snapshot tools',
+    },
+    browser: {
+      type: 'boolean',
+      description: 'Force browser tools',
+      default: false,
+    },
+    'out-dir': {
+      type: 'string',
+      description: 'Directory for new tests',
+      default: 'tests/e2e',
+    },
+    write: {
+      type: 'boolean',
+      description: 'Write files into the project',
+      default: true,
+    },
+  },
+  async run({ args }) {
+    const recipes = String(args.recipes || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const focus = String(args.focus || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    consola.start('Covering missing tests with AI');
+    const result = await coverMissingTests({
+      root: resolve(String(args.root)),
+      recipes,
+      focus,
+      baseURL: args['base-url'] ? String(args['base-url']) : undefined,
+      browser: Boolean(args.browser || args['base-url']),
+      outDir: String(args['out-dir']),
+      write: Boolean(args.write),
+    });
+
+    for (const f of result.files) {
+      consola.success(f.path);
+    }
+    consola.info(`fingerprint ${result.fingerprint.slice(0, 12)}…`);
+  },
+});

package/src/commands/doctor.ts

@@ -0,0 +1,107 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'pathe';
+import { createRequire } from 'node:module';
+import { findMonorepoRoot } from '../utils/workspace';
+
+type Check = { ok: boolean; label: string; hint?: string; optional?: boolean };
+
+function canResolve(id: string, cwd: string): boolean {
+  try {
+    const req = createRequire(join(cwd, 'package.json'));
+    req.resolve(id);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const doctorCommand = defineCommand({
+  meta: {
+    name: 'doctor',
+    description: 'Check untestutils environment and configs',
+  },
+  args: {
+    cwd: {
+      type: 'string',
+      description: 'Project directory',
+      default: '.',
+    },
+  },
+  async run({ args }) {
+    const cwd = resolve(String(args.cwd));
+    const checks: Check[] = [];
+    const mono = findMonorepoRoot(cwd);
+
+    const major = Number(process.versions.node.split('.')[0]);
+    checks.push({
+      ok: major >= 20,
+      label: `Node.js ${process.version}`,
+      hint: 'Requires Node >= 20',
+    });
+
+    for (const id of ['untestutils', 'vitest'] as const) {
+      checks.push({
+        ok: canResolve(id, cwd) || Boolean(mono),
+        label: `package ${id}`,
+        hint: `pnpm add -D ${id}`,
+      });
+    }
+
+    for (const id of ['@playwright/test', 'playwright-core', 'nuxt'] as const) {
+      const ok = canResolve(id, cwd) || (Boolean(mono) && id !== 'nuxt');
+      checks.push({
+        ok,
+        optional: true,
+        label: `optional: ${id}`,
+        hint: ok ? undefined : `needed for the matching preset (pnpm add -D ${id})`,
+      });
+    }
+
+    const configCandidates = [
+      'vitest.config.ts',
+      'vitest.config.mts',
+      'vitest.config.js',
+      'playwright.config.ts',
+      'playwright.config.mts',
+      'vitest.unit.config.ts',
+    ];
+    const hasConfig = Boolean(mono) || configCandidates.some((f) => existsSync(join(cwd, f)));
+    checks.push({
+      ok: hasConfig,
+      label: 'vitest/playwright config',
+      hint: 'untestutils init --preset vitest',
+    });
+
+    const hasRecipes =
+      Boolean(mono) ||
+      existsSync(join(cwd, 'recipes.ts')) ||
+      existsSync(join(cwd, 'tests/recipes.ts')) ||
+      existsSync(join(cwd, 'e2e/recipes.ts'));
+    checks.push({
+      ok: hasRecipes,
+      label: 'recipes.ts',
+      hint: 'create defineRecipes(...) or run init',
+    });
+
+    let failed = 0;
+    for (const c of checks) {
+      if (c.ok) {
+        consola.success(c.label);
+      } else if (c.optional) {
+        consola.info(`${c.label}${c.hint ? ` — ${c.hint}` : ''}`);
+      } else {
+        failed++;
+        consola.error(`${c.label}${c.hint ? ` — ${c.hint}` : ''}`);
+      }
+    }
+
+    if (failed > 0) {
+      consola.warn(`Issues: ${failed}`);
+      process.exitCode = 1;
+    } else {
+      consola.success('Environment looks good');
+    }
+  },
+});

package/src/commands/fix.ts

@@ -0,0 +1,113 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'pathe';
+import { execSync } from 'node:child_process';
+import { fixBrokenTests } from '@untestutils/ai';
+import { pathExists, writeText } from '../utils/fs';
+
+export const fixCommand = defineCommand({
+  meta: {
+    name: 'fix',
+    description: 'Fix a broken untestutils test via AI (failure log + optional browser tools)',
+  },
+  args: {
+    path: {
+      type: 'positional',
+      description: 'Failing test file',
+      required: true,
+    },
+    log: {
+      type: 'string',
+      description: 'Path to failure log file (or use --run)',
+      alias: 'l',
+    },
+    run: {
+      type: 'string',
+      description: 'Shell command that fails (stdout/stderr captured as log)',
+    },
+    root: {
+      type: 'string',
+      description: 'Project root',
+      default: '.',
+    },
+    recipes: {
+      type: 'string',
+      description: 'Comma-separated recipe ids',
+      default: '',
+    },
+    'base-url': {
+      type: 'string',
+      description: 'App base URL for Playwright page tools',
+    },
+    browser: {
+      type: 'boolean',
+      description: 'Enable browser tools even without --base-url',
+      default: false,
+    },
+    write: {
+      type: 'boolean',
+      description: 'Overwrite the failing file in place',
+      default: true,
+    },
+    out: {
+      type: 'string',
+      description: 'Write fixed source to this path instead',
+    },
+  },
+  async run({ args }) {
+    const file = resolve(String(args.path));
+    if (!(await pathExists(file))) {
+      consola.error(`File not found: ${file}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    let failureLog = '';
+    if (args.log) {
+      failureLog = await readFile(resolve(String(args.log)), 'utf8');
+    } else if (args.run) {
+      consola.start(`Running: ${args.run}`);
+      try {
+        execSync(String(args.run), {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+          cwd: resolve(String(args.root)),
+        });
+        consola.warn('Command succeeded — nothing to fix');
+        return;
+      } catch (e: unknown) {
+        const err = e as { stdout?: string; stderr?: string; message?: string };
+        failureLog = `${err.stdout ?? ''}\n${err.stderr ?? ''}\n${err.message ?? ''}`;
+      }
+    } else {
+      consola.error('Provide --log <file> or --run "<test command>"');
+      process.exitCode = 1;
+      return;
+    }
+
+    const recipes = String(args.recipes || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    consola.start(`Fixing ${file}`);
+    const result = await fixBrokenTests({
+      path: file,
+      root: resolve(String(args.root)),
+      failureLog,
+      recipes,
+      baseURL: args['base-url'] ? String(args['base-url']) : undefined,
+      browser: Boolean(args.browser || args['base-url']),
+      write: false,
+    });
+
+    const outPath = args.out ? resolve(String(args.out)) : file;
+    if (args.write || args.out) {
+      await writeText(outPath, result.code);
+      consola.success(`Wrote ${outPath}`);
+    } else {
+      consola.success(`Cached fix at ${result.genPath}`);
+    }
+  },
+});

package/src/commands/index.ts

@@ -0,0 +1,17 @@
+import { initCommand } from './init';
+import { convertCommand } from './convert';
+import { aiCommand } from './ai';
+import { doctorCommand } from './doctor';
+import { fixCommand } from './fix';
+import { coverCommand } from './cover';
+import { perfCommand } from './perf';
+
+export const commands = {
+  init: initCommand,
+  convert: convertCommand,
+  ai: aiCommand,
+  fix: fixCommand,
+  cover: coverCommand,
+  doctor: doctorCommand,
+  perf: perfCommand,
+};

package/src/commands/init.ts

@@ -0,0 +1,74 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { addDependency } from 'nypm';
+import { resolve } from 'pathe';
+import { applyPreset, peersForPreset, type InitPreset } from '../utils/templates';
+
+const PRESETS: InitPreset[] = ['vitest', 'playwright', 'nuxt', 'full'];
+
+export const initCommand = defineCommand({
+  meta: {
+    name: 'init',
+    description: 'Add base untestutils configs and example tests to a project',
+  },
+  args: {
+    preset: {
+      type: 'string',
+      description: 'Preset: vitest | playwright | nuxt | full',
+      default: 'vitest',
+      alias: 'p',
+    },
+    cwd: {
+      type: 'string',
+      description: 'Project directory',
+      default: '.',
+    },
+    force: {
+      type: 'boolean',
+      description: 'Overwrite existing files',
+      default: false,
+    },
+    install: {
+      type: 'boolean',
+      description: 'Install peer dependencies via nypm',
+      default: true,
+    },
+  },
+  async run({ args }) {
+    const preset = String(args.preset) as InitPreset;
+    if (!PRESETS.includes(preset)) {
+      consola.error(`Unknown preset "${preset}". Available: ${PRESETS.join(', ')}`);
+      process.exitCode = 1;
+      return;
+    }
+    const cwd = resolve(String(args.cwd));
+    consola.start(`Initializing untestutils (preset=${preset}) in ${cwd}`);
+    const written = await applyPreset(cwd, preset, { force: Boolean(args.force) });
+    if (written.length === 0) {
+      consola.info('No new files — already present (or use --force)');
+    } else {
+      consola.success(`Created files: ${written.length}`);
+    }
+
+    if (args.install) {
+      const deps = peersForPreset(preset);
+      consola.start(`Installing dependencies: ${deps.join(', ')}`);
+      try {
+        await addDependency(deps, { cwd, silent: false });
+        consola.success('Dependencies installed');
+      } catch (e) {
+        consola.warn(`Could not install automatically: ${e}`);
+        consola.info(`Install manually: ${deps.join(' ')}`);
+      }
+    }
+
+    consola.box(
+      [
+        'Next steps:',
+        '  1. Review recipes.ts and fixture app paths',
+        '  2. pnpm test / npx vitest run',
+        '  3. untestutils doctor — environment check',
+      ].join('\n'),
+    );
+  },
+});

package/src/commands/perf.ts

@@ -0,0 +1,77 @@
+import { defineCommand } from 'citty';
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'pathe';
+import { consola } from 'consola';
+
+export const perfCommand = defineCommand({
+  meta: {
+    name: 'perf',
+    description: [
+      'Run a build+load performance suite from a config module.',
+      '',
+      'Examples:',
+      '  untestutils perf --config ./perf.config.ts',
+      '  untestutils perf --config ./perf.config.ts --only micro --skip-load',
+      '  untestutils perf --config ./perf.config.ts --runs 3 --json',
+    ].join('\n'),
+  },
+  args: {
+    config: {
+      type: 'string',
+      required: true,
+      description: 'Path to perf.config.ts exporting definePerfSuite(...) or default suite',
+    },
+    only: {
+      type: 'string',
+      description: 'Target id(s), comma-separated',
+    },
+    runs: {
+      type: 'string',
+      description: 'Override consecutive runs',
+    },
+    skipLoad: {
+      type: 'boolean',
+      default: false,
+      description: 'Measure builds only (skip autocannon/artillery)',
+    },
+    json: {
+      type: 'boolean',
+      default: false,
+      description: 'Also write JSON report under artifactsDir',
+    },
+  },
+  async run({ args }) {
+    const configPath = resolve(args.config);
+    const mod = (await import(pathToFileURL(configPath).href)) as {
+      default?: unknown;
+      suite?: unknown;
+    };
+    const suite = (mod.default ?? mod.suite) as import('@untestutils/perf').PerfSuite | undefined;
+    if (!suite || !Array.isArray((suite as { targets?: unknown }).targets)) {
+      consola.error('Config must default-export a PerfSuite (definePerfSuite({ targets: [...] }))');
+      process.exitCode = 1;
+      return;
+    }
+
+    const { runPerfSuite } = await import('@untestutils/perf');
+    const only = args.only
+      ? args.only
+          .split(',')
+          .map((s: string) => s.trim())
+          .filter(Boolean)
+      : undefined;
+    const runs = args.runs ? Number(args.runs) : undefined;
+    if (runs !== undefined && (!Number.isFinite(runs) || runs < 1)) {
+      consola.error('--runs must be a positive number');
+      process.exitCode = 1;
+      return;
+    }
+
+    await runPerfSuite(suite, {
+      only,
+      runs,
+      skipLoad: args.skipLoad,
+      json: args.json,
+    });
+  },
+});

package/src/main.ts

@@ -0,0 +1,46 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineCommand } from 'citty';
+import { commands } from './commands';
+
+function readOwnVersion(): string {
+  try {
+    const req = createRequire(import.meta.url);
+    // published: dist/cli-run.mjs → ../package.json ; monorepo facade/cli package.json
+    for (const cand of [
+      join(dirname(fileURLToPath(import.meta.url)), '../package.json'),
+      join(dirname(fileURLToPath(import.meta.url)), '../../package.json'),
+    ]) {
+      try {
+        const pkg = req(cand) as { name?: string; version?: string };
+        if (pkg.version && (pkg.name === 'untestutils' || pkg.name === '@untestutils/cli')) {
+          return pkg.version;
+        }
+      } catch {
+        /* try next */
+      }
+    }
+  } catch {
+    /* fall through */
+  }
+  return '0.0.0';
+}
+
+export const main = defineCommand({
+  meta: {
+    name: 'untestutils',
+    version: readOwnVersion(),
+    description: [
+      'CLI for untestutils: init, AI generate/fix/cover, doctor, monorepo helpers.',
+      '',
+      'Examples:',
+      '  untestutils init --preset vitest',
+      '  untestutils fix tests/e2e/broken.test.ts --run "pnpm vitest run tests/e2e/broken.test.ts"',
+      '  untestutils cover --base-url http://127.0.0.1:3000 --recipes site',
+      '  untestutils doctor',
+      '  untestutils --help',
+    ].join('\n'),
+  },
+  subCommands: commands,
+});

package/src/run.ts

@@ -0,0 +1,7 @@
+import { runMain } from 'citty';
+import { main } from './main';
+
+// pnpm `run … -- --flag` forwards a bare `--`; citty then treats flags after it as positionals.
+process.argv = process.argv.filter((arg) => arg !== '--');
+
+runMain(main);

package/src/utils/fs.ts

@@ -0,0 +1,37 @@
+import { mkdir, writeFile, readFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname } from 'pathe';
+import { consola } from 'consola';
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeIfMissing(
+  path: string,
+  content: string,
+  opts: { force?: boolean } = {},
+): Promise<'wrote' | 'skipped'> {
+  if (!opts.force && (await pathExists(path))) {
+    consola.info(`skip (exists): ${path}`);
+    return 'skipped';
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, 'utf8');
+  consola.success(`wrote: ${path}`);
+  return 'wrote';
+}
+
+export async function readText(path: string): Promise<string> {
+  return readFile(path, 'utf8');
+}
+
+export async function writeText(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, 'utf8');
+}

package/src/utils/templates.ts

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'pathe';
+import { templatesRoot } from './workspace';
+import { writeIfMissing } from './fs';
+
+export type InitPreset = 'vitest' | 'playwright' | 'nuxt' | 'full';
+
+/** Relative template paths under src/templates */
+const PRESET_FILES: Record<InitPreset, string[]> = {
+  vitest: ['vitest/vitest.config.ts', 'vitest/recipes.ts', 'vitest/tests/e2e/smoke.test.ts'],
+  playwright: [
+    'playwright/playwright.config.ts',
+    'playwright/recipes.ts',
+    'playwright/tests/e2e/smoke.spec.ts',
+  ],
+  nuxt: ['nuxt/vitest.config.ts', 'nuxt/recipes.ts', 'nuxt/tests/e2e/smoke.test.ts'],
+  full: [
+    'vitest/vitest.config.ts',
+    'playwright/playwright.config.ts',
+    'nuxt/recipes.ts',
+    'vitest/tests/e2e/smoke.test.ts',
+    'playwright/tests/e2e/smoke.spec.ts',
+    'nuxt/tests/e2e/nuxt-smoke.test.ts',
+  ],
+};
+
+function destFromTemplate(rel: string): string {
+  const parts = rel.split('/');
+  parts.shift();
+  return parts.join('/');
+}
+
+export async function applyPreset(
+  cwd: string,
+  preset: InitPreset,
+  opts: { force?: boolean } = {},
+): Promise<string[]> {
+  const root = templatesRoot();
+  const files = PRESET_FILES[preset];
+  const written: string[] = [];
+  const seen = new Set<string>();
+
+  for (const rel of files) {
+    const destRel = destFromTemplate(rel);
+    if (seen.has(destRel)) continue;
+    seen.add(destRel);
+    const content = await readFile(join(root, rel), 'utf8');
+    const dest = join(cwd, destRel);
+    const result = await writeIfMissing(dest, content, opts);
+    if (result === 'wrote') written.push(destRel);
+  }
+  return written;
+}
+
+export function peersForPreset(preset: InitPreset): string[] {
+  const base = ['untestutils', 'vitest'];
+  if (preset === 'playwright' || preset === 'full') {
+    base.push('@playwright/test', 'playwright-core');
+  }
+  if (preset === 'nuxt' || preset === 'full') {
+    base.push('nuxt');
+  }
+  return [...new Set(base)];
+}

package/src/utils/workspace.ts

@@ -0,0 +1,80 @@
+import { join, dirname } from 'pathe';
+import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync } from 'node:fs';
+
+/** Untestutils monorepo root when the CLI runs inside this repository. */
+export function findMonorepoRoot(start = process.cwd()): string | null {
+  let dir = start;
+  for (let i = 0; i < 12; i++) {
+    if (
+      existsSync(join(dir, 'pnpm-workspace.yaml')) &&
+      existsSync(join(dir, 'packages/untestutils/package.json'))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function cliPackageRoot(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const name = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: string }).name;
+        if (name === '@untestutils/cli') return dir;
+      } catch {
+        /* continue */
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(dirname(fileURLToPath(import.meta.url)), '../..');
+}
+
+export function templatesRoot(): string {
+  const mono = findMonorepoRoot();
+  if (mono) {
+    const fromMono = join(mono, 'packages/cli/templates');
+    if (existsSync(fromMono)) return fromMono;
+  }
+  const root = cliPackageRoot();
+  for (const c of [
+    join(root, 'templates'),
+    join(root, 'dist/templates'),
+    join(root, 'src/templates'),
+  ]) {
+    if (existsSync(c)) return c;
+  }
+  // bundled into untestutils facade (legacy) or published package
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const name = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: string }).name;
+        if (name === 'untestutils' || name === '@untestutils/cli') {
+          for (const c of [
+            join(dir, 'templates'),
+            join(dir, 'dist/templates'),
+            join(dir, 'src/templates'),
+          ]) {
+            if (existsSync(c)) return c;
+          }
+        }
+      } catch {
+        /* continue */
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(cliPackageRoot(), 'templates');
+}

package/templates/nuxt/recipes.ts

@@ -0,0 +1,14 @@
+import { defineRecipes } from 'untestutils';
+import { nuxt } from 'untestutils/nuxt';
+import { resolve } from 'node:path';
+
+/** root — Nuxt app directory (e.g. playground or fixtures/nuxt). */
+export const recipes = defineRecipes(
+  {
+    app: nuxt({
+      id: 'app',
+      root: resolve('./fixtures/nuxt'),
+    }),
+  },
+  import.meta.url,
+);

package/templates/nuxt/tests/e2e/nuxt-smoke.test.ts

@@ -0,0 +1,9 @@
+import { describe, test, expect, useHarness } from 'untestutils/vitest';
+
+describe('nuxt smoke', () => {
+  test('app returns HTML', async () => {
+    const app = await useHarness('app');
+    const res = await fetch(app.url!);
+    expect(res.ok).toBe(true);
+  });
+});

package/templates/nuxt/tests/e2e/smoke.test.ts

@@ -0,0 +1,9 @@
+import { describe, test, expect, useHarness } from 'untestutils/vitest';
+
+describe('nuxt smoke', () => {
+  test('app returns HTML', async () => {
+    const app = await useHarness('app');
+    const res = await fetch(app.url!);
+    expect(res.ok).toBe(true);
+  });
+});

package/templates/nuxt/tests/unit/smoke.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+import { mountSuspended } from 'untestutils/runtime';
+
+describe('unit smoke', () => {
+  it('mountSuspended is available', async () => {
+    expect(typeof mountSuspended).toBe('function');
+  });
+});

package/templates/nuxt/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config';
+import { untestutils } from 'untestutils/vitest/plugin';
+import { recipes } from './recipes';
+
+/**
+ * E2e harness project. Keep unit Nuxt env in a *separate* Vitest config
+ * (see vitest.unit.config.ts) — do not mix `untestutils()` plugin with
+ * `environment: 'untestutils'` in one project.
+ */
+export default defineConfig({
+  plugins: [
+    untestutils({
+      recipes,
+      prewarm: ['app'],
+    }),
+  ],
+  test: {
+    include: ['tests/e2e/**/*.test.ts'],
+    testTimeout: 120_000,
+  },
+});

package/templates/nuxt/vitest.unit.config.ts

@@ -0,0 +1,16 @@
+import { fileURLToPath } from 'node:url';
+import { defineVitestProject } from 'untestutils/config';
+
+/** In-process Nuxt unit project — separate from e2e harness config. */
+export default defineVitestProject({
+  test: {
+    name: 'unit-nuxt',
+    include: ['tests/unit/**/*.{test,spec}.ts'],
+    environmentOptions: {
+      nuxt: {
+        rootDir: fileURLToPath(new URL('.', import.meta.url)),
+        domEnvironment: 'happy-dom',
+      },
+    },
+  },
+});

package/templates/playwright/playwright.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from '@playwright/test';
+import { createPlaywrightConfig } from 'untestutils/playwright';
+import { recipes } from './recipes';
+
+export default defineConfig(
+  createPlaywrightConfig({
+    recipes,
+    session: 'app-pw',
+    prewarm: ['basic'],
+    workers: 2,
+    fullyParallel: true,
+    testDir: './tests/e2e',
+    use: {
+      headless: true,
+    },
+  }),
+);

package/templates/playwright/recipes.ts

@@ -0,0 +1,12 @@
+import { defineRecipes, staticDir } from 'untestutils';
+import { resolve } from 'node:path';
+
+export const recipes = defineRecipes(
+  {
+    basic: staticDir({
+      id: 'basic',
+      root: resolve('./fixtures/basic'),
+    }),
+  },
+  import.meta.url,
+);

package/templates/playwright/tests/e2e/smoke.spec.ts

@@ -0,0 +1,8 @@
+import { test, expect } from 'untestutils/playwright';
+
+test.use({ harness: 'basic' });
+
+test('page opens', async ({ page, baseURL }) => {
+  expect(baseURL).toBeTruthy();
+  await page.goto('/');
+});

package/templates/vitest/recipes.ts

@@ -0,0 +1,13 @@
+import { defineRecipes, staticDir } from 'untestutils';
+import { resolve } from 'node:path';
+
+/** Replace root with your fixture app path (static folder or Nuxt). */
+export const recipes = defineRecipes(
+  {
+    basic: staticDir({
+      id: 'basic',
+      root: resolve('./fixtures/basic'),
+    }),
+  },
+  import.meta.url,
+);

package/templates/vitest/tests/e2e/smoke.test.ts

@@ -0,0 +1,8 @@
+import { describe, test, expect, useHarness } from 'untestutils/vitest';
+
+describe('smoke', () => {
+  test('harness starts', async () => {
+    const app = await useHarness('basic');
+    expect(app.url).toBeTruthy();
+  });
+});

package/templates/vitest/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+import { untestutils } from 'untestutils/vitest/plugin';
+import { recipes } from './recipes';
+
+export default defineConfig({
+  plugins: [
+    untestutils({
+      recipes,
+      prewarm: ['basic'],
+    }),
+  ],
+  test: {
+    include: ['tests/e2e/**/*.test.ts'],
+    testTimeout: 60_000,
+  },
+});