@emeryld/manager 1.5.1 → 1.5.2

package/dist/publish.js

@@ -13,6 +13,7 @@ import { publishCliState } from './prompts.js';
 import { createRrrPackage, runCreatePackageCli, } from './create-package/index.js';
 import { runRobot } from './robot/index.js';
 import { runDocsFeature } from './docs/index.js';
+import { runTypeScriptTraceProfiler, runTypeScriptTraceReportCli, } from './ts-trace/index.js';
 import { colors, logGlobal } from './utils/log.js';
 import { run } from './utils/run.js';
 const MANAGER_PACKAGE = '@emeryld/manager';
@@ -187,7 +188,7 @@ async function runPackageSelectionLoop(packages, helperArgs) {
                 {
                     name: 'utils',
                     emoji: '🛠️',
-                    description: 'Docs, format checker, robot metadata, and package scaffolding',
+                    description: 'Docs, format checker, TypeScript trace profiler, robot metadata, and package scaffolding',
                     handler: async () => {
                         // eslint-disable-next-line no-constant-condition
                         while (true) {
@@ -210,6 +211,14 @@ async function runPackageSelectionLoop(packages, helperArgs) {
                                             await runFormatChecker();
                                         },
                                     },
+                                    {
+                                        name: 'typescript trace profiler',
+                                        emoji: '⏱️',
+                                        description: 'Analyze TypeScript generateTrace output and rank slow files, spans, and type relations',
+                                        handler: async () => {
+                                            await runTypeScriptTraceProfiler();
+                                        },
+                                    },
                                     {
                                         name: 'robot metadata',
                                         emoji: '🤖',
@@ -258,6 +267,15 @@ async function main() {
         await runFormatCheckerScanCli(cliArgs.slice(1));
         return;
     }
+    if (cliArgs[0] === 'ts-trace') {
+        if (cliArgs.length === 1) {
+            await runTypeScriptTraceProfiler();
+        }
+        else {
+            await runTypeScriptTraceReportCli(cliArgs.slice(1));
+        }
+        return;
+    }
     const parsed = parseCliArgs(cliArgs);
     const packages = await loadPackages();
     // If user provided non-interactive flags, run headless path
@@ -294,5 +312,11 @@ async function main() {
 }
 main().catch((error) => {
     console.error(error);
-    process.exit(1);
+    const exitCode = typeof error === 'object' &&
+        error !== null &&
+        'exitCode' in error &&
+        typeof error.exitCode === 'number'
+        ? error.exitCode
+        : 1;
+    process.exit(exitCode);
 });

package/dist/ts-trace/cli/options.js

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import { colors } from '../../utils/log.js';
+export function parseTraceReportCliArgs(argv, defaults) {
+    let traceDir;
+    let targetPath;
+    let projectPath = defaults.projectPath;
+    let top = defaults.top;
+    let minMs = defaults.minMs;
+    let json = defaults.includeJson;
+    let filterRegex = defaults.filterRegex;
+    let eventNames = [...defaults.eventNames];
+    let didProvideEventFlag = false;
+    let baseDir = defaults.baseDir;
+    let outPath = defaults.outPath;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--help' || token === '-h') {
+            return { help: true };
+        }
+        if (token === '--json') {
+            json = true;
+            continue;
+        }
+        if (token === '--traceDir' || token === '--trace-dir') {
+            const raw = argv[++i];
+            if (!raw)
+                throw new Error('Flag "--traceDir" expects a directory path.');
+            traceDir = raw;
+            continue;
+        }
+        if (token === '--target') {
+            const raw = argv[++i];
+            if (!raw)
+                throw new Error('Flag "--target" expects a file or folder path.');
+            targetPath = raw;
+            continue;
+        }
+        if (token === '--project') {
+            const raw = argv[++i];
+            if (!raw)
+                throw new Error('Flag "--project" expects a tsconfig path.');
+            projectPath = raw;
+            continue;
+        }
+        if (token === '--top') {
+            const raw = argv[++i];
+            const parsed = parsePositiveInteger(raw);
+            if (parsed === undefined) {
+                throw new Error('Flag "--top" expects a positive integer.');
+            }
+            top = parsed;
+            continue;
+        }
+        if (token === '--minMs' || token === '--min-ms') {
+            const raw = argv[++i];
+            const parsed = parseNonNegativeNumber(raw);
+            if (parsed === undefined) {
+                throw new Error('Flag "--minMs" expects a non-negative number.');
+            }
+            minMs = parsed;
+            continue;
+        }
+        if (token === '--filter') {
+            const raw = argv[++i];
+            if (raw === undefined) {
+                throw new Error('Flag "--filter" expects a regex string.');
+            }
+            ensureRegex(raw);
+            filterRegex = raw;
+            continue;
+        }
+        if (token === '--event') {
+            const raw = argv[++i];
+            if (!raw)
+                throw new Error('Flag "--event" expects an event name.');
+            if (!didProvideEventFlag) {
+                eventNames = [];
+            }
+            didProvideEventFlag = true;
+            eventNames.push(raw);
+            continue;
+        }
+        if (token === '--baseDir' || token === '--base-dir') {
+            const raw = argv[++i];
+            if (!raw)
+                throw new Error('Flag "--baseDir" expects a path.');
+            baseDir = raw;
+            continue;
+        }
+        if (token === '--out') {
+            const raw = argv[++i];
+            if (!raw)
+                throw new Error('Flag "--out" expects a file path.');
+            outPath = raw;
+            json = true;
+            continue;
+        }
+        throw new Error(`Unknown option "${token}". Use "pnpm manager-cli ts-trace --help".`);
+    }
+    if (traceDir && targetPath) {
+        throw new Error('Use either --traceDir (existing trace) or --target (generate trace), not both.');
+    }
+    const reportBase = {
+        top,
+        minMs,
+        json,
+        filterRegex,
+        eventNames: normalizeEventNames(eventNames),
+        baseDir: path.resolve(baseDir || process.cwd()),
+        outPath: outPath ? path.resolve(outPath) : undefined,
+    };
+    if (traceDir) {
+        return {
+            help: false,
+            command: {
+                mode: 'existing',
+                report: {
+                    traceDir: path.resolve(traceDir),
+                    ...reportBase,
+                },
+            },
+        };
+    }
+    if (targetPath) {
+        return {
+            help: false,
+            command: {
+                mode: 'generate',
+                targetPath: path.resolve(targetPath),
+                projectPath: projectPath ? path.resolve(projectPath) : undefined,
+                report: reportBase,
+            },
+        };
+    }
+    throw new Error('Provide one of: --target <file|folder> (generate trace) or --traceDir <path> (analyze existing).');
+}
+export function printTraceReportUsage() {
+    console.log(colors.bold('Usage: pnpm manager-cli ts-trace [flags]'));
+    console.log(colors.dim('Profile TypeScript checker speed by target path, or analyze an existing --generateTrace directory.'));
+    console.log('');
+    console.log(`${colors.cyan('--target <path>')}\tProfile a file/folder (auto-generates trace then reports offenders).`);
+    console.log(`${colors.cyan('--project <tsconfig>')}\tOptional project config for generation (default: auto-detect).`);
+    console.log(`${colors.cyan('--traceDir <path>')}\tAnalyze an already-generated trace directory with trace.json/types.json.`);
+    console.log(`${colors.cyan('--top <n>')}\tShow top results per table. Defaults to workspace settings or 20.`);
+    console.log(`${colors.cyan('--json')}\tPrint machine-readable JSON in addition to tables.`);
+    console.log(`${colors.cyan('--filter <regex>')}\tFilter events by matching file path.`);
+    console.log(`${colors.cyan('--event <name>')}\tInclude only specified event names (repeatable).`);
+    console.log(`${colors.cyan('--minMs <n>')}\tIgnore events shorter than n ms (default 1).`);
+    console.log(`${colors.cyan('--baseDir <path>')}\tBase directory for relative display paths.`);
+    console.log(`${colors.cyan('--out <path>')}\tWrite JSON report to file (implies --json).`);
+    console.log('');
+    console.log(colors.dim('Example (auto profile): pnpm manager-cli ts-trace --target src/format-checker --top 30'));
+    console.log(colors.dim('Example (existing trace): pnpm manager-cli ts-trace --traceDir /tmp/ts-trace-foo --json --out /tmp/ts-report.json'));
+    console.log(colors.dim('Large traces: set NODE_OPTIONS="--max-old-space-size=4096" before running if needed.'));
+}
+function parsePositiveInteger(raw) {
+    if (!raw)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    const floored = Math.floor(parsed);
+    if (floored <= 0)
+        return undefined;
+    return floored;
+}
+function parseNonNegativeNumber(raw) {
+    if (!raw)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    if (parsed < 0)
+        return undefined;
+    return parsed;
+}
+function normalizeEventNames(eventNames) {
+    const seen = new Set();
+    const normalized = [];
+    for (const value of eventNames) {
+        const trimmed = value.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}
+function ensureRegex(raw) {
+    try {
+        new RegExp(raw);
+    }
+    catch (error) {
+        throw new Error(`Flag "--filter" received an invalid regex: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/ts-trace/cli/prompts.js

@@ -0,0 +1,148 @@
+import { stdin as input } from 'node:process';
+import path from 'node:path';
+import { colors } from '../../utils/log.js';
+import { askLine, promptSingleKey } from '../../prompts.js';
+import { promptInteractiveSettings, } from '../../cli/interactive-settings.js';
+import { SETTING_DESCRIPTORS, formatValue, parseBooleanInput, parseInteractiveValue, parseNumericValue, parseStringList, validateTraceSettings, } from './settings.js';
+import { rootDir } from '../../helper-cli/env.js';
+const READY_PROMPT = colors.dim('Settings retained. Adjust values and confirm when ready.');
+export async function promptTraceReportSettings(defaults) {
+    const supportsInteractive = typeof input.setRawMode === 'function' && input.isTTY;
+    let currentSettings = defaults;
+    while (true) {
+        const chosen = supportsInteractive
+            ? await promptSettingsInteractive(currentSettings)
+            : await promptSettingsSequential(currentSettings);
+        const confirmed = await confirmExecution();
+        if (confirmed)
+            return normalizePromptSettings(chosen);
+        currentSettings = normalizePromptSettings(chosen);
+        console.log(READY_PROMPT);
+    }
+}
+async function confirmExecution() {
+    const question = colors.cyan('Save these settings? (Y/n): ');
+    return promptSingleKey(question, (key) => {
+        const normalized = key.trim().toLowerCase();
+        if (!normalized || normalized === 'y' || normalized === 'yes')
+            return true;
+        if (normalized === 'n' || normalized === 'no')
+            return false;
+        return undefined;
+    });
+}
+async function promptSettingsInteractive(defaults) {
+    const descriptors = SETTING_DESCRIPTORS.map((descriptor) => ({
+        key: descriptor.key,
+        label: descriptor.label,
+        unit: descriptor.unit,
+        format: (value) => formatValue(value, descriptor),
+        parse: (buffer) => parseInteractiveValue(descriptor, buffer),
+    }));
+    return promptInteractiveSettings({
+        title: 'TypeScript trace profiler settings (type to edit values)',
+        descriptors,
+        initial: defaults,
+        instructions: [
+            'Use ↑/↓ to change rows, type to replace the highlighted value, Backspace to clear characters, and Enter to validate and confirm the selection.',
+            'Press Esc/Ctrl+C to abort, or hit Enter again after reviewing the summary to continue.',
+        ],
+        validate: validateTraceSettings,
+    });
+}
+async function promptSettingsSequential(defaults) {
+    console.log(colors.dim('Enter values to override defaults or press Enter to keep them.'));
+    const top = await promptPositiveInteger('Top results', defaults.top);
+    const minMs = await promptNonNegativeNumber('Minimum span duration (ms)', defaults.minMs);
+    const filterRegex = await promptText('Path filter regex', defaults.filterRegex);
+    const eventNames = await promptEvents(defaults.eventNames);
+    const includeJson = await promptBoolean('Print JSON report in terminal', defaults.includeJson);
+    const outPath = await promptText('JSON output file path', defaults.outPath);
+    const baseDir = await promptPath('Display base directory', defaults.baseDir || rootDir);
+    const projectPath = await promptText('TypeScript project config path (blank = auto)', defaults.projectPath);
+    return {
+        top,
+        minMs,
+        filterRegex,
+        eventNames,
+        includeJson: includeJson || false,
+        outPath,
+        baseDir,
+        projectPath,
+    };
+}
+async function promptPositiveInteger(label, fallback) {
+    const question = colors.cyan(`${label} [default ${fallback}]: `);
+    while (true) {
+        const answer = await askLine(question);
+        if (!answer)
+            return fallback;
+        const parsed = parseNumericValue(answer);
+        if (parsed !== undefined && parsed > 0)
+            return Math.floor(parsed);
+        console.log(colors.yellow('Provide a positive number or leave blank.'));
+    }
+}
+async function promptNonNegativeNumber(label, fallback) {
+    const question = colors.cyan(`${label} [default ${fallback}]: `);
+    while (true) {
+        const answer = await askLine(question);
+        if (!answer)
+            return fallback;
+        const parsed = parseNumericValue(answer);
+        if (parsed !== undefined && parsed >= 0)
+            return parsed;
+        console.log(colors.yellow('Provide a non-negative number or leave blank.'));
+    }
+}
+async function promptBoolean(label, fallback) {
+    const question = colors.cyan(`${label} [default ${fallback ? 'yes' : 'no'}]: `);
+    while (true) {
+        const answer = (await askLine(question)).trim();
+        if (!answer)
+            return fallback;
+        const parsed = parseBooleanInput(answer);
+        if (parsed.error) {
+            console.log(colors.yellow(parsed.error));
+            continue;
+        }
+        return parsed.value;
+    }
+}
+async function promptText(label, fallback) {
+    const question = colors.cyan(`${label} [default ${fallback || '(none)'}]: `);
+    const answer = await askLine(question);
+    if (!answer)
+        return fallback;
+    return answer.trim();
+}
+async function promptEvents(fallback) {
+    const fallbackLabel = fallback.length ? fallback.join(', ') : '(all events)';
+    const question = colors.cyan(`Event names [default ${fallbackLabel}]: `);
+    const answer = await askLine(question);
+    if (!answer)
+        return fallback;
+    return parseStringList(answer);
+}
+async function promptPath(label, fallback) {
+    const question = colors.cyan(`${label} [default ${fallback}]: `);
+    const answer = await askLine(question);
+    if (!answer)
+        return fallback;
+    const trimmed = answer.trim();
+    if (!trimmed)
+        return fallback;
+    return path.isAbsolute(trimmed) ? trimmed : path.resolve(rootDir, trimmed);
+}
+function normalizePromptSettings(settings) {
+    return {
+        ...settings,
+        top: Math.max(1, Math.floor(settings.top)),
+        minMs: Math.max(0, settings.minMs),
+        filterRegex: settings.filterRegex.trim(),
+        eventNames: settings.eventNames.map((name) => name.trim()).filter(Boolean),
+        outPath: settings.outPath.trim(),
+        baseDir: settings.baseDir.trim() || rootDir,
+        projectPath: settings.projectPath.trim(),
+    };
+}

package/dist/ts-trace/cli/settings.js

@@ -0,0 +1,154 @@
+export const SETTING_DESCRIPTORS = [
+    {
+        key: 'top',
+        label: 'Top results',
+        unit: 'entries',
+        type: 'number',
+    },
+    {
+        key: 'minMs',
+        label: 'Minimum span duration',
+        unit: 'milliseconds',
+        type: 'number',
+        allowZero: true,
+    },
+    {
+        key: 'filterRegex',
+        label: 'Path filter regex',
+        unit: 'blank = include all',
+        type: 'text',
+    },
+    {
+        key: 'eventNames',
+        label: 'Event names',
+        unit: 'comma-separated, blank = all',
+        type: 'list',
+    },
+    {
+        key: 'includeJson',
+        label: 'Print JSON in terminal',
+        type: 'boolean',
+    },
+    {
+        key: 'outPath',
+        label: 'JSON output path',
+        unit: 'blank = no file output',
+        type: 'text',
+    },
+    {
+        key: 'baseDir',
+        label: 'Display base directory',
+        type: 'text',
+    },
+    {
+        key: 'projectPath',
+        label: 'TypeScript project config',
+        unit: 'blank = auto-detect',
+        type: 'text',
+    },
+];
+export function formatValue(value, descriptor) {
+    if (descriptor.type === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (descriptor.type === 'list') {
+        const list = value;
+        return list.length ? list.join(', ') : 'all events';
+    }
+    if (descriptor.type === 'text') {
+        const text = `${value}`.trim();
+        return text || '(none)';
+    }
+    return `${value}`;
+}
+export function parseInteractiveValue(descriptor, buffer) {
+    const trimmed = buffer.trim();
+    if (trimmed === '') {
+        if (descriptor.type === 'list')
+            return { value: [] };
+        if (descriptor.type === 'text')
+            return { value: '' };
+        return { value: undefined };
+    }
+    if (descriptor.type === 'number') {
+        const parsed = parseNumericValue(trimmed);
+        if (parsed === undefined) {
+            const rangeLabel = descriptor.allowZero ? 'non-negative' : 'positive';
+            return { error: `${descriptor.label} requires a ${rangeLabel} number.` };
+        }
+        if (!descriptor.allowZero && parsed <= 0) {
+            return { error: `${descriptor.label} requires a positive number.` };
+        }
+        if (descriptor.allowZero && parsed < 0) {
+            return { error: `${descriptor.label} must be non-negative.` };
+        }
+        if (descriptor.key === 'top') {
+            return { value: Math.floor(parsed) };
+        }
+        return { value: parsed };
+    }
+    if (descriptor.type === 'boolean') {
+        const parsed = parseBooleanInput(trimmed);
+        if (parsed.error)
+            return { error: parsed.error };
+        return { value: parsed.value };
+    }
+    if (descriptor.type === 'list') {
+        const events = parseStringList(trimmed);
+        return {
+            value: events,
+        };
+    }
+    if (descriptor.key === 'filterRegex') {
+        try {
+            // Validate early so mistakes are caught inside the settings page.
+            new RegExp(trimmed);
+        }
+        catch (error) {
+            return {
+                error: error instanceof Error ? error.message : 'Invalid regex pattern.',
+            };
+        }
+    }
+    return { value: trimmed };
+}
+export function validateTraceSettings(settings) {
+    if (!Number.isFinite(settings.top) || settings.top <= 0) {
+        return 'Top results must be a positive number.';
+    }
+    if (!Number.isFinite(settings.minMs) || settings.minMs < 0) {
+        return 'Minimum span duration must be non-negative.';
+    }
+    if (settings.filterRegex) {
+        try {
+            new RegExp(settings.filterRegex);
+        }
+        catch (error) {
+            return `Path filter regex is invalid: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    if (!settings.baseDir.trim()) {
+        return 'Display base directory cannot be empty.';
+    }
+    return undefined;
+}
+export function parseNumericValue(raw) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    return parsed;
+}
+export function parseBooleanInput(raw) {
+    const normalized = raw.trim().toLowerCase();
+    if (['yes', 'y', 'true', '1'].includes(normalized))
+        return { value: true };
+    if (['no', 'n', 'false', '0'].includes(normalized))
+        return { value: false };
+    return { error: 'Provide "true" or "false".' };
+}
+export function parseStringList(raw) {
+    return raw
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}

package/dist/ts-trace/config.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { rootDir } from '../helper-cli/env.js';
+const SETTINGS_SECTION = 'manager.tsTraceProfiler';
+const workspaceSettingsPath = path.join(rootDir, '.vscode', 'settings.json');
+export const DEFAULT_TRACE_REPORT_SETTINGS = {
+    top: 20,
+    minMs: 1,
+    filterRegex: '',
+    eventNames: [],
+    includeJson: false,
+    outPath: '',
+    baseDir: rootDir,
+    projectPath: '',
+};
+export async function loadTraceReportSettings() {
+    if (!existsSync(workspaceSettingsPath)) {
+        return DEFAULT_TRACE_REPORT_SETTINGS;
+    }
+    try {
+        const raw = await readFile(workspaceSettingsPath, 'utf8');
+        const json = JSON.parse(raw);
+        const section = json[SETTINGS_SECTION];
+        if (!section || typeof section !== 'object') {
+            return DEFAULT_TRACE_REPORT_SETTINGS;
+        }
+        const record = section;
+        return {
+            top: coercePositiveInteger(record.top, DEFAULT_TRACE_REPORT_SETTINGS.top),
+            minMs: coerceNonNegativeNumber(record.minMs, DEFAULT_TRACE_REPORT_SETTINGS.minMs),
+            filterRegex: coerceString(record.filterRegex, DEFAULT_TRACE_REPORT_SETTINGS.filterRegex),
+            eventNames: coerceStringArray(record.eventNames, DEFAULT_TRACE_REPORT_SETTINGS.eventNames),
+            includeJson: coerceBoolean(record.includeJson, DEFAULT_TRACE_REPORT_SETTINGS.includeJson),
+            outPath: coerceString(record.outPath, DEFAULT_TRACE_REPORT_SETTINGS.outPath),
+            baseDir: coerceBaseDir(record.baseDir, DEFAULT_TRACE_REPORT_SETTINGS.baseDir),
+            projectPath: coerceString(record.projectPath, DEFAULT_TRACE_REPORT_SETTINGS.projectPath),
+        };
+    }
+    catch {
+        return DEFAULT_TRACE_REPORT_SETTINGS;
+    }
+}
+function coercePositiveInteger(value, fallback) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    const floored = Math.floor(parsed);
+    if (floored <= 0)
+        return fallback;
+    return floored;
+}
+function coerceNonNegativeNumber(value, fallback) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    if (parsed < 0)
+        return fallback;
+    return parsed;
+}
+function coerceString(value, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    return value.trim();
+}
+function coerceStringArray(value, fallback) {
+    if (Array.isArray(value)) {
+        const parsed = value
+            .map((item) => (typeof item === 'string' ? item.trim() : ''))
+            .filter(Boolean);
+        return parsed;
+    }
+    if (typeof value === 'string') {
+        return value
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    return fallback;
+}
+function coerceBoolean(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'true')
+            return true;
+        if (normalized === 'false')
+            return false;
+    }
+    return fallback;
+}
+function coerceBaseDir(value, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return fallback;
+    return path.isAbsolute(trimmed) ? trimmed : path.resolve(rootDir, trimmed);
+}