@emeryld/manager 1.5.0 → 1.5.2

package/dist/helper-cli.js

@@ -1,5 +1,6 @@
 import { colors } from './helper-cli/colors.js';
 import { printScriptList } from './helper-cli/display.js';
+import { promptForScriptMultiSelect } from './helper-cli/multi-select.js';
 import { promptForScript } from './helper-cli/prompts.js';
 import { findScriptEntry, normalizeScripts } from './helper-cli/scripts.js';
 import { runEntry } from './helper-cli/runner.js';
@@ -40,3 +41,35 @@ export async function runHelperCli({ scripts, title = 'Helper CLI', argv = proce
     }
     return false;
 }
+export async function runHelperCliMultiSelect({ scripts, title = 'Helper CLI', argv = process.argv.slice(2), }) {
+    const normalized = normalizeScripts(scripts);
+    let args = Array.isArray(argv) ? [...argv] : [];
+    const separatorIndex = args.indexOf('--');
+    if (separatorIndex !== -1) {
+        args = [...args.slice(0, separatorIndex), ...args.slice(separatorIndex + 1)];
+    }
+    const [firstArg] = args;
+    if (firstArg === '--list' || firstArg === '-l') {
+        printScriptList(normalized, title);
+        return undefined;
+    }
+    if (firstArg === '--help' || firstArg === '-h') {
+        console.log(colors.magenta('Usage:'));
+        console.log('  pnpm run <cli> [script]');
+        console.log('\nFlags:');
+        console.log('  --list  Show available scripts');
+        console.log('  --help  Show this information');
+        return undefined;
+    }
+    const argLooksLikeScript = firstArg && !firstArg.startsWith('-');
+    if (argLooksLikeScript) {
+        const requested = findScriptEntry(normalized, firstArg);
+        if (requested)
+            return [requested.displayName];
+        console.log(colors.yellow(`Unknown script "${firstArg}". Falling back to interactive selection…`));
+    }
+    const selection = await promptForScriptMultiSelect(normalized, title);
+    if (!selection)
+        return undefined;
+    return selection.map((entry) => entry.displayName);
+}

package/dist/menu.js

@@ -9,8 +9,6 @@ import { ensureWorkingTreeCommitted } from './preflight.js';
 import { openDockerHelper } from './docker.js';
 import { run } from './utils/run.js';
 import { makeBaseScriptEntries, getPackageMarker, getPackageModule } from './menu/script-helpers.js';
-import { runFormatChecker } from './format-checker/index.js';
-import { runRobot } from './robot/index.js';
 import { describeVersionControlScope, makeVersionControlEntries, } from './version-control.js';
 function formatKindLabel(kind) {
     if (kind === 'cli')
@@ -70,22 +68,6 @@ function makeManagerStepEntries(targets, packages, state) {
                 state.lastStep = 'test';
             },
         },
-        {
-            name: 'format checker',
-            emoji: '🧮',
-            description: 'Scan for long functions, deep indentation, too many files/components, and repeated snippets',
-            handler: async () => {
-                await runFormatChecker();
-            },
-        },
-        {
-            name: 'robot metadata',
-            emoji: '🤖',
-            description: 'Collect functions, components, types, consts, and classes across the workspace',
-            handler: async () => {
-                await runRobot();
-            },
-        },
         {
             name: 'build',
             emoji: '🏗️',

package/dist/publish.js

@@ -7,10 +7,13 @@ import { runHelperCli } from './helper-cli.js';
 import { buildPackageSelectionMenu, runStepLoop } from './menu.js';
 import { getOrderedPackages, loadPackages, resolvePackage } from './packages.js';
 import { releaseMultiple, releaseSingle, } from './release.js';
-import { runFormatCheckerScanCli } from './format-checker/index.js';
+import { runFormatChecker, runFormatCheckerScanCli } from './format-checker/index.js';
 import { ensureWorkingTreeCommitted } from './preflight.js';
 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';
@@ -183,12 +186,62 @@ async function runPackageSelectionLoop(packages, helperArgs) {
                     lastStep = step;
                 }),
                 {
-                    name: 'Create package',
-                    emoji: '✨',
-                    description: 'Scaffold a new rrr package (contract/server/client)',
+                    name: 'utils',
+                    emoji: '🛠️',
+                    description: 'Docs, format checker, TypeScript trace profiler, robot metadata, and package scaffolding',
                     handler: async () => {
-                        await createRrrPackage();
-                        currentPackages = await loadPackages();
+                        // eslint-disable-next-line no-constant-condition
+                        while (true) {
+                            const ranUtility = await runHelperCli({
+                                title: 'Utilities',
+                                scripts: [
+                                    {
+                                        name: 'docs',
+                                        emoji: '📚',
+                                        description: 'Pick files from .manager-docs and copy a bundled payload to clipboard',
+                                        handler: async () => {
+                                            await runDocsFeature();
+                                        },
+                                    },
+                                    {
+                                        name: 'format checker',
+                                        emoji: '🧮',
+                                        description: 'Scan for long functions, deep indentation, and repeated snippets',
+                                        handler: async () => {
+                                            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: '🤖',
+                                        description: 'Collect functions, components, types, consts, and classes',
+                                        handler: async () => {
+                                            await runRobot();
+                                        },
+                                    },
+                                    {
+                                        name: 'Create package',
+                                        emoji: '✨',
+                                        description: 'Scaffold a new rrr package (contract/server/client)',
+                                        handler: async () => {
+                                            await createRrrPackage();
+                                            currentPackages = await loadPackages();
+                                        },
+                                    },
+                                ],
+                                argv: [],
+                            });
+                            if (!ranUtility)
+                                break;
+                        }
                         lastStep = 'back';
                     },
                 },
@@ -214,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
@@ -238,7 +300,7 @@ async function main() {
         return;
     }
     if (packages.length === 0) {
-        logGlobal('No packages found (no package.json discovered). Use "Create package" to scaffold one.', colors.yellow);
+        logGlobal('No packages found (no package.json discovered). Use "utils" -> "Create package" to scaffold one.', colors.yellow);
     }
     // Interactive flow (unchanged): selection menu then step menu
     if (parsed.selectionArg) {
@@ -250,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(),
+    };
+}