@emeryld/manager 1.3.1 → 1.4.0

package/README.md

@@ -92,6 +92,37 @@ The same knobs live in `.vscode/settings.json` under `manager.robot`, for exampl
 }
 ```
 
+### Robot pack settings reference
+
+The same `manager.robot` block that backs the metadata helper is merged with the defaults listed in `src/robot/pack/types.ts` before every robot pack build. The helper always uses the directory you select at runtime as the `rootDir`, so you only need to override the other keys. Here is what each option controls:
+
+| Setting | Description | Default |
+| --- | --- | --- |
+| `tsconfigPath` | Optional path (relative to the selected root) pointing to a `tsconfig.json`. When omitted the builder climbs parent directories until it finds one. | Auto-detect the nearest `tsconfig.json`. |
+| `includeGlobs` | Glob patterns that determine which `.ts/.tsx` files are scanned. | `["src/**/*.{ts,tsx}"]` |
+| `excludeGlobs` | Globs that are skipped (tests, build output, declaration files, etc.) so they never contribute symbols. | `["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/dist/**", "**/build/**", "**/*.d.ts"]` |
+| `entrypoints` | Modules that seed the exported-symbol walk when `exportMode` is `entrypoints`. If none of the globs match, the first included file is used as a fallback so the pack is never empty. | `["src/index.ts", "src/**/index.ts"]` |
+| `exportMode` | Choose between `entrypoints` (only mirror the modules matched above) and `all-files` (treat every included file as an entrypoint). Use `entrypoints` to scope the pack to a few roots; `all-files` is the default so nothing is accidentally omitted. | `all-files` |
+| `visibility` | `exported-only` (default) keeps only exported symbols, `exported+reexported` also follows re-exports from other modules, and `all` additionally captures the local declarations that live in the same file. | `exported-only` |
+| `includeKinds` | Which symbol kinds to keep—choose any combination of `function`, `class`, `interface`, `type-alias`, `enum`, and `const` to filter the pack down to your preferred abstractions. | `["function", "class", "interface", "type-alias", "enum", "const"]` |
+| `closure` | `surface-only` keeps just the exported declarations, while `surface+deps` (default) also includes their dependency closure. The latter also enables trimming dependency types when a `tokenBudget` is in play. | `surface+deps` |
+| `maxExemplars` | Maximum number of exemplar functions/classes that are appended to the pack. The builder also caps each module to about half this number so the samples cover more files. | `8` |
+| `tokenBudget` | Optional cap on estimated tokens (pack text length ÷ 4). When the estimate exceeds the budget the helper drops exemplars first, then—if `closure` is `surface+deps`—it drops dependency type declarations until the estimate fits. Leave blank for unlimited. | Unlimited |
+| `preferTypeSurface` | Accepted for compatibility and shown in the interactive prompt, but the current builder ignores this flag. | `true` |
+| `exemplarHeuristics` | Weights that tune the new utility-per-token scoring (usage, boundary, flow, clarity, redundancy) plus the token penalty scale. | `{"usage":6,"boundary":1.2,"flow":1.3,"clarity":0.8,"redundancy":0.6,"tau":280}` |
+| `keepJSDocTags` | List of JSDoc tags that survive the minification step when exemplar bodies are emitted. Tags lacking an `@` automatically get one added. | `["@deprecated", "@throws", "@pure", "@sideEffects", "@internal", "@public", "@experimental", "@llm"]` |
+
+`exemplarHeuristics` now drives a utility-per-token score that favors usage-focused, boundary-aware, and flow-respecting chunks while penalizing redundancy and excessive size.
+
+- `usage` (default `6`) strongly weights snippets that show real call-site arguments, defaults, or error handling.
+- `boundary` (default `1.2`) favors chunks that touch configuration, CLI wiring, filesystem/serialization, or output paths.
+- `flow` (default `1.3`) boosts exemplars on entrypoint-to-output paths, including the traced flow exemplar when available.
+- `clarity` (default `0.8`) rewards clear naming, preserved doc tags, and explicit error strings.
+- `redundancy` (default `0.6`) subtracts from candidates that closely overlap already-selected snippets.
+- `tau` (default `280`) sets the denominator for the size penalty, anchoring chunk length around ~200–300 tokens.
+
+Every exemplar is paired with metadata (`purpose`, `when_relevant`, `symbols_shown`) plus a declared purpose bucket (orchestration/pipeline, configuration/normalization, parsing/validation, selection/filtering, core domain algorithm, or I/O boundary) so downstream LLM consumers can immediately understand why the snippet matters, when to consult it, and which angle it covers.
+
 ### Example output
 `robot metadata` prints a summary followed by the parsed payload. With the default formatting you get readable JSON:
 

package/dist/create-package/cli-args.js

@@ -0,0 +1,78 @@
+import { colors, logGlobal } from '../utils/log.js';
+export function parseCreateCliArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--list' || arg === '-l' || arg === 'list' || arg === 'ls') {
+            options.list = true;
+            continue;
+        }
+        if (arg === '--describe' || arg === '-d' || arg === 'describe') {
+            options.describe = argv[++i];
+            continue;
+        }
+        if (arg === '--variant' || arg === '-v') {
+            options.variant = argv[++i];
+            continue;
+        }
+        if (arg === '--dir' || arg === '--path' || arg === '-p') {
+            options.targetDir = argv[++i];
+            continue;
+        }
+        if (arg === '--name' || arg === '-n') {
+            options.pkgName = argv[++i];
+            continue;
+        }
+        if (arg === '--contract') {
+            options.contractName = argv[++i];
+            continue;
+        }
+        if (arg === '--client-kind' || arg === '--client') {
+            options.clientKind = argv[++i];
+            continue;
+        }
+        if (arg === '--skip-install') {
+            options.skipInstall = true;
+            continue;
+        }
+        if (arg === '--skip-build') {
+            options.skipBuild = true;
+            continue;
+        }
+        if (arg === '--reset') {
+            options.reset = true;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (!arg.startsWith('-') && !options.variant) {
+            options.variant = arg;
+        }
+    }
+    return options;
+}
+export function printCreateHelp() {
+    logGlobal('Create package help', colors.magenta);
+    console.log('Usage:');
+    console.log('  pnpm manager-cli create                     # interactive prompts');
+    console.log('  pnpm manager-cli create --list              # list templates');
+    console.log('  pnpm manager-cli create --describe rrr-server');
+    console.log('  pnpm manager-cli create --variant rrr-client --dir packages/rrr-client --name @scope/client');
+    console.log('  pnpm manager-cli create --variant rrr-server --contract @scope/contract --skip-install');
+    console.log('  pnpm manager-cli create --variant rrr-server --reset # blow away an existing target before scaffolding');
+    console.log('');
+    console.log('Flags:');
+    console.log('  --list, -l          Show available templates');
+    console.log('  --describe, -d      Print details for a template');
+    console.log('  --variant, -v       Pick a template by id/label (skips variant prompt)');
+    console.log('  --dir, --path, -p   Target directory (skips path prompt)');
+    console.log('  --name, -n          Package name (skips name prompt)');
+    console.log('  --contract          Contract import to inject (server/client variants)');
+    console.log('  --client-kind       Client stack (vite-react | expo-react-native)');
+    console.log('  --reset             Remove the target directory if it already exists');
+    console.log('  --skip-install      Do not run pnpm install after scaffolding');
+    console.log('  --skip-build        Skip build after scaffolding');
+    console.log('  --help, -h          Show this help');
+}

package/dist/create-package/prompts.js

@@ -0,0 +1,138 @@
+import path from 'node:path';
+import { colors, logGlobal } from '../utils/log.js';
+import { runHelperCli } from '../helper-cli.js';
+import { askLine } from '../prompts.js';
+import { loadPackages } from '../packages.js';
+import { ensureTargetDir } from './tasks.js';
+import { derivePackageName, VARIANTS } from './variant-info.js';
+import { CLIENT_KIND_OPTIONS, DEFAULT_CLIENT_KIND, normalizeClientKind, } from './variants/client.js';
+import { workspaceRoot } from './shared.js';
+async function promptForContractNameWithHelper(title, options) {
+    let selection;
+    const scripts = options.map((opt) => ({
+        name: opt.label,
+        description: opt.meta ?? '',
+        emoji: '📦',
+        handler: () => {
+            selection = opt.value;
+        },
+    }));
+    scripts.push({
+        name: 'Enter manually',
+        emoji: '⌨️',
+        description: 'Type a contract package name',
+        handler: async () => {
+            const manual = await askLine('Contract package name (e.g. @scope/contract): ');
+            selection = manual.trim() || undefined;
+        },
+    });
+    scripts.push({
+        name: 'Skip (no contract)',
+        emoji: '⏭️',
+        description: 'Continue without a contract dependency',
+        handler: () => {
+            selection = undefined;
+        },
+    });
+    await runHelperCli({ title, scripts, argv: [] });
+    return selection;
+}
+export async function promptForContractName() {
+    let packages = [];
+    try {
+        packages = await loadPackages();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'unknown error discovering packages';
+        logGlobal(`Could not auto-discover packages (${message}).`, colors.yellow);
+    }
+    const contractOptions = packages
+        .filter((pkg) => pkg.relativeDir !== '.')
+        .map((pkg) => ({
+        value: pkg.name,
+        label: pkg.name,
+        meta: pkg.relativeDir,
+    }));
+    if (contractOptions.length === 0) {
+        const manual = await askLine('Contract package name? (Enter to skip, e.g. @scope/contract): ');
+        return manual.trim() || undefined;
+    }
+    return promptForContractNameWithHelper('Select a contract package (or skip)', contractOptions);
+}
+export async function promptForClientKind(existing) {
+    const defaultKind = normalizeClientKind(existing) ?? DEFAULT_CLIENT_KIND;
+    let selection;
+    const scripts = CLIENT_KIND_OPTIONS.map((opt) => ({
+        name: opt.label,
+        emoji: opt.id == 'vite-react' ? '💻' : opt.id == 'expo-react-native' ? '📱' : '🌐',
+        description: opt.summary,
+        handler: () => {
+            selection = opt.id;
+        },
+    }));
+    await runHelperCli({
+        title: 'Select a client template',
+        scripts,
+        argv: [],
+    });
+    return selection ?? defaultKind;
+}
+export async function promptForVariant() {
+    let selection;
+    const scripts = VARIANTS.map((variant) => ({
+        name: variant.label,
+        emoji: '✨',
+        description: variant.summary
+            ? `${variant.summary} · ${variant.defaultDir}`
+            : variant.defaultDir,
+        handler: () => {
+            selection = variant;
+        },
+    }));
+    while (!selection) {
+        await runHelperCli({
+            title: 'Pick a package template',
+            scripts,
+            argv: [],
+        });
+    }
+    return selection;
+}
+export async function promptForTargetDir(fallback) {
+    const answer = await askLine(`Path for the new package? (${fallback}): `);
+    const normalized = answer || fallback;
+    return path.resolve(workspaceRoot, normalized);
+}
+export async function gatherTarget(initial = {}) {
+    const variant = initial.variant ?? (await promptForVariant());
+    const targetDir = initial.targetDir !== undefined
+        ? path.resolve(workspaceRoot, initial.targetDir)
+        : await promptForTargetDir(variant.defaultDir);
+    const fallbackName = derivePackageName(targetDir);
+    const nameAnswer = initial.pkgName === undefined
+        ? await askLine(`Package name? (${fallbackName}): `)
+        : initial.pkgName;
+    const pkgName = (nameAnswer || fallbackName).trim() || fallbackName;
+    await ensureTargetDir(targetDir, { reset: initial.reset });
+    let contractName = initial.contractName;
+    if ((variant.id === 'rrr-server' || variant.id === 'rrr-client') &&
+        contractName === undefined) {
+        contractName = await promptForContractName();
+    }
+    let clientKind = initial.clientKind;
+    if (variant.id === 'rrr-client' || variant.id === 'rrr-fullstack') {
+        const normalizedKind = normalizeClientKind(clientKind);
+        clientKind = normalizedKind ?? clientKind;
+        if (!clientKind) {
+            clientKind = await promptForClientKind();
+        }
+    }
+    return {
+        variant,
+        targetDir,
+        pkgName,
+        contractName,
+        clientKind,
+        reset: initial.reset,
+    };
+}

package/dist/create-package/shared/configs.js

@@ -0,0 +1,309 @@
+import { access } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { ModuleResolutionKind } from 'typescript';
+import { workspaceRoot } from './constants.js';
+export function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+}
+export async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function baseTsConfig(options) {
+    const config = {
+        ...(options?.extends ? { extends: options.extends } : {}),
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            ...(options?.outDir ? { outDir: options.outDir } : {}),
+            ...(options?.rootDir ? { rootDir: options.rootDir } : {}),
+            declaration: options?.declaration ?? true,
+            sourceMap: options?.sourceMap ?? true,
+            strict: options?.strict ?? true,
+            esModuleInterop: options?.esModuleInterop ?? true,
+            skipLibCheck: options?.skipLibCheck ?? true,
+            resolveJsonModule: options?.resolveJsonModule ?? true,
+            forceConsistentCasingInFileNames: options?.forceConsistentCasingInFileNames ?? true,
+            baseUrl: options?.baseUrl ?? '.',
+            lib: options?.lib,
+            types: options?.types,
+            jsx: options?.jsx,
+        },
+        include: options?.include,
+        exclude: options?.exclude,
+    };
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+export function baseEslintConfig(tsconfigPath = './tsconfig.json') {
+    return `import tseslint from 'typescript-eslint'
+import prettierPlugin from 'eslint-plugin-prettier'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules'] },
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        project: ${JSON.stringify(tsconfigPath)},
+        tsconfigRootDir: __dirname,
+      },
+    },
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    rules: {
+      'prettier/prettier': 'error',
+      '@typescript-eslint/consistent-type-imports': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^ignore' },
+      ],
+    },
+  },
+)
+`;
+}
+export function basePrettierConfig() {
+    return `export default {
+  singleQuote: true,
+  semi: false,
+  trailingComma: 'all',
+  printWidth: 100,
+}
+`;
+}
+export const PRETTIER_IGNORE = ['node_modules', 'dist', '.turbo', 'coverage', '*.log'].join('\n');
+export const LINT_STAGED_CONFIG = {
+    '*.{ts,tsx}': ['eslint --fix'],
+    '*.{ts,tsx,js,jsx,json,md,css,html}': ['prettier --write'],
+};
+export const HUSKY_PRE_COMMIT = `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm lint-staged
+`;
+export function vscodeSettings() {
+    return `${JSON.stringify({
+        'editor.defaultFormatter': 'esbenp.prettier-vscode',
+        'editor.formatOnSave': true,
+        'editor.codeActionsOnSave': {
+            'source.fixAll.eslint': 'always',
+            'source.organizeImports': true,
+        },
+        'eslint.useFlatConfig': true,
+        'eslint.format.enable': true,
+        'eslint.validate': ['typescript', 'javascript'],
+        'files.eol': '\n',
+        'prettier.requireConfig': true,
+    }, null, 2)}\n`;
+}
+export const BASE_LINT_DEV_DEPENDENCIES = {
+    typescript: '^5.9.3',
+    eslint: '^9.12.0',
+    'eslint-plugin-prettier': '^5.2.1',
+    prettier: '^3.3.3',
+    'typescript-eslint': '^8.10.0',
+    rimraf: '^6.0.1',
+    tsx: '^4.19.0',
+    husky: '^9.1.6',
+    'lint-staged': '^15.2.10',
+    '@emeryld/manager': 'latest',
+};
+const DEFAULT_GITIGNORE_ENTRIES = [
+    'node_modules',
+    'dist',
+    '.turbo',
+    '.DS_Store',
+    '.env',
+    'coverage',
+    '*.log',
+    '.vscode',
+    '.husky',
+];
+export function gitignoreFrom(entries = DEFAULT_GITIGNORE_ENTRIES) {
+    return entries.join('\n');
+}
+export function baseScripts(devCommand, extras, options) {
+    const includePrepare = options?.includePrepare ?? true;
+    return {
+        dev: devCommand,
+        build: 'tsc -p tsconfig.json',
+        typecheck: 'tsc -p tsconfig.json --noEmit',
+        lint: 'eslint . --max-warnings=0',
+        'lint:fix': 'eslint . --fix',
+        'lint-staged': 'lint-staged',
+        format: 'prettier . --write',
+        'format:check': 'prettier . --check',
+        clean: 'rimraf dist .turbo coverage',
+        test: "node -e \"console.log('No tests yet')\"",
+        ...(includePrepare
+            ? { prepare: 'git rev-parse --is-inside-work-tree >/dev/null 2>&1 && husky || true' }
+            : {}),
+        ...extras,
+    };
+}
+export function basePackageFiles(options) {
+    return {
+        '.gitignore': gitignoreFrom(options?.gitignoreEntries),
+    };
+}
+export const SCRIPT_DESCRIPTIONS = {
+    dev: 'Watch and rebuild on change',
+    build: 'Type-check and emit to dist/',
+    typecheck: 'Type-check only (no emit)',
+    lint: 'Run ESLint with flat config',
+    'lint:fix': 'Fix lint issues automatically',
+    'lint-staged': 'Run lint/format on staged files',
+    format: 'Format code with Prettier',
+    'format:check': 'Check formatting without writing',
+    clean: 'Remove build artifacts and caches',
+    test: 'Placeholder test script',
+    start: 'Run the built output',
+    'docker:build': 'Build docker image',
+    'docker:up': 'Build and start container',
+    'docker:dev': 'Build, start, and tail logs',
+    'docker:logs': 'Tail docker logs',
+    'docker:stop': 'Stop running container',
+    'docker:clean': 'Stop and remove container',
+    'docker:reset': 'Remove container and image',
+};
+export function buildReadme(options) {
+    const scripts = options.scripts ?? [];
+    const scriptLines = scripts.map((script) => {
+        const desc = SCRIPT_DESCRIPTIONS[script];
+        return desc ? `- \`npm run ${script}\` - ${desc}` : `- \`npm run ${script}\``;
+    });
+    const sections = [...(options.sections ?? [])];
+    if (scriptLines.length > 0) {
+        sections.push({ title: 'Scripts', lines: scriptLines });
+    }
+    const lines = [`# ${options.name}`, ''];
+    if (options.description) {
+        lines.push(options.description, '');
+    }
+    sections.forEach((section) => {
+        lines.push(`## ${section.title}`, ...section.lines, '');
+    });
+    return `${lines.join('\n').trim()}\n`;
+}
+export function basePackageJson(options) {
+    const applyDefaults = options.useDefaults ?? true;
+    const inheritPackageManager = options.inheritPackageManager ?? true;
+    const packageManager = inheritPackageManager && !options.extraFields?.packageManager
+        ? readRootPackageManager()
+        : undefined;
+    const pkg = stripUndefined({
+        name: options.name,
+        version: options.version ?? '0.1.0',
+        private: options.private ?? true,
+        ...(applyDefaults
+            ? {
+                type: options.type ?? 'module',
+                main: options.main ?? 'dist/index.js',
+                types: options.types ?? 'dist/index.d.ts',
+                files: options.files ?? ['dist'],
+            }
+            : stripUndefined({
+                type: options.type,
+                main: options.main,
+                types: options.types,
+                files: options.files,
+            })),
+        exports: options.exports,
+        scripts: options.scripts,
+        dependencies: options.dependencies,
+        devDependencies: options.devDependencies,
+        'lint-staged': LINT_STAGED_CONFIG,
+        packageManager,
+        ...options.extraFields,
+    });
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+function readRootPackageManager() {
+    try {
+        const raw = readFileSync(path.join(workspaceRoot, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        return pkg.packageManager;
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            error.code !== 'ENOENT') {
+            console.warn(`Could not read root package.json for packageManager: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return undefined;
+    }
+}
+export async function resolveRootTsconfig(baseDir = workspaceRoot) {
+    const candidates = ['tsconfig.base.json', 'tsconfig.json'];
+    for (const candidate of candidates) {
+        const fullPath = path.join(baseDir, candidate);
+        if (await pathExists(fullPath)) {
+            return fullPath;
+        }
+    }
+    return undefined;
+}
+export async function findNearestTsconfig(startDir) {
+    let current = path.resolve(startDir);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const found = await resolveRootTsconfig(current);
+        if (found)
+            return found;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+export async function packageTsConfig(targetDir, options) {
+    const extendsFromRoot = options?.extendsFromRoot ?? true;
+    let extendsPath;
+    if (extendsFromRoot) {
+        const rootConfig = await findNearestTsconfig(targetDir);
+        if (rootConfig) {
+            const relative = path.relative(targetDir, rootConfig);
+            const normalized = toPosixPath(relative || './tsconfig.base.json');
+            extendsPath = normalized.startsWith('.') ? normalized : `./${normalized}`;
+        }
+    }
+    const compilerOptions = stripUndefined({
+        rootDir: options?.rootDir ?? 'src',
+        outDir: options?.outDir ?? 'dist',
+        tsBuildInfoFile: 'dist/.tsbuildinfo',
+        jsx: options?.jsx,
+        types: options?.types,
+        lib: options?.lib,
+        esModuleInterop: options?.esModuleInterop ?? true,
+        allowSyntheticDefaultImports: options?.esModuleInterop ?? true,
+        skipLibCheck: options?.skipLibCheck ?? true,
+        target: options?.target,
+        module: options?.module,
+        moduleResolution: options?.ModuleResolutionKind !== undefined
+            ? ModuleResolutionKind[options.ModuleResolutionKind]
+            : undefined,
+        declaration: options?.declarationMap,
+        declarationMap: options?.declarationMap,
+    });
+    const config = stripUndefined({
+        extends: extendsPath,
+        compilerOptions,
+        include: options?.include ?? ['src/**/*.ts'],
+    });
+    return `${JSON.stringify(config, null, 2)}\n`;
+}

package/dist/create-package/shared/constants.js

@@ -0,0 +1,5 @@
+import path from 'node:path';
+export const workspaceRoot = process.cwd();
+export function isWorkspaceRoot(dir) {
+    return path.resolve(dir) === path.resolve(workspaceRoot);
+}

package/dist/create-package/shared/fs-utils.js

@@ -0,0 +1,69 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promptYesNoAll } from '../../prompts.js';
+import { baseEslintConfig, basePrettierConfig, HUSKY_PRE_COMMIT, pathExists, PRETTIER_IGNORE, resolveRootTsconfig, toPosixPath, vscodeSettings, } from './configs.js';
+import { workspaceRoot } from './constants.js';
+export async function writeFileIfMissing(baseDir, relative, contents) {
+    const fullPath = path.join(baseDir, relative);
+    await mkdir(path.dirname(fullPath), { recursive: true });
+    try {
+        await access(fullPath);
+        const rel = path.relative(workspaceRoot, fullPath);
+        console.log(`  skipped ${rel} (already exists)`);
+        return 'skipped';
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await writeFile(fullPath, contents, 'utf8');
+    const rel = path.relative(workspaceRoot, fullPath);
+    console.log(`  created ${rel}`);
+    return 'created';
+}
+export async function writeFileWithPrompt(baseDir, relative, contents) {
+    const fullPath = path.join(baseDir, relative);
+    await mkdir(path.dirname(fullPath), { recursive: true });
+    const rel = path.relative(workspaceRoot, fullPath);
+    const exists = await pathExists(fullPath);
+    if (exists) {
+        const answer = await promptYesNoAll(`Overwrite existing ${rel}?`);
+        if (answer !== 'yes') {
+            console.log(`  kept existing ${rel}`);
+            return 'skipped';
+        }
+    }
+    await writeFile(fullPath, contents, 'utf8');
+    console.log(`  ${exists ? 'updated' : 'created'} ${rel}`);
+    return exists ? 'updated' : 'created';
+}
+export function workspaceToolingFiles(tsconfigPath) {
+    return {
+        'eslint.config.js': baseEslintConfig(tsconfigPath),
+        'prettier.config.js': basePrettierConfig(),
+        '.prettierignore': `${PRETTIER_IGNORE}\n`,
+        '.vscode/settings.json': vscodeSettings(),
+        '.husky/pre-commit': HUSKY_PRE_COMMIT,
+    };
+}
+export async function ensureWorkspaceToolingFiles(baseDir, options) {
+    const defaultTsconfig = path.join(baseDir, 'tsconfig.json');
+    const resolvedRootConfig = options?.tsconfigPath
+        ? path.resolve(baseDir, options.tsconfigPath)
+        : await resolveRootTsconfig(baseDir);
+    const relativeTsconfig = path.relative(baseDir, resolvedRootConfig ?? defaultTsconfig);
+    const normalized = toPosixPath(relativeTsconfig || './tsconfig.json');
+    const tsconfigPath = normalized.startsWith('.') ? normalized : `./${normalized}`;
+    const files = workspaceToolingFiles(tsconfigPath);
+    for (const [relative, contents] of Object.entries(files)) {
+        await writeFileWithPrompt(baseDir, relative, contents);
+    }
+}
+export async function writeFilesIfMissing(baseDir, files) {
+    for (const [relative, contents] of Object.entries(files)) {
+        await writeFileIfMissing(baseDir, relative, contents);
+    }
+}