@emeryld/manager 1.4.15 → 1.5.1

package/README.md

@@ -11,16 +11,24 @@ Dev dependency built for Codex agents: scan a pnpm workspace, scaffold RRRoutes
 - Headless publish: `pnpm manager-cli all --non-interactive --bump patch --tag next`
 
 ## Running `manager-cli` interactively
-- **Package selection**: scans for every `package.json` (ignores node_modules/dist). Menu entries include each package (color-coded), "All packages", and "Create package". Navigate with ↑/↓/j/k or digits to run instantly.
+- **Package selection**: scans for every `package.json` (ignores node_modules/dist). Menu entries include each package (color-coded), "All packages", and a root-level `utils` submenu (`docs`, format checker, robot metadata, create package). Navigate with ↑/↓/j/k or digits to run instantly.
 - **Action menu** for the selection:
   - `update dependencies` → runs `pnpm -r update` (or filtered update), stages only dependency files, prompts for a commit message, commits, and pushes.
   - `test` → `pnpm test` (filtered to the package when possible).
-  - `format checker` → prompts for limits, then scans each source file for long functions and class methods, deep indentation, too many components/functions, and repeated/similar snippets before reporting offenders.
   - `build` → `pnpm build` (filtered when a single package is selected).
   - `publish` → ensures the working tree is committed, checks registry auth, prompts a version strategy, commits the bump, tags, publishes with pnpm, and pushes tags.
   - `full` → update → test → build → publish in order.
 - `back` → return to package selection. When a single package is chosen, its `package.json` scripts also appear as runnable entries.
 
+## Docs feature
+
+From the root picker, open `utils` -> `docs`.
+
+- The helper creates/uses `.manager-docs` in your workspace root.
+- Drop files into that folder.
+- Toggle files on/off in the interactive picker (checked rows are included).
+- Press `Space` to bundle all checked files and copy the result to your clipboard.
+
 ## Format checker configuration
 
 `manager-cli` ships with a format checker action that respects defaults in `.vscode/settings.json` under the `manager.formatChecker` key. Define:
@@ -107,7 +115,7 @@ Before the extraction runs you can also choose how to consume the results. The d
 To keep the payload more token-friendly, the interactive settings screen now exposes `Condense output for compact JSON` and `Docstring length limit`. Enabling the condensed output replaces the verbose object format with a small `fields` + `rows` array layout, and the docstring limit trims comments to the first N characters (set the value to `0` for unlimited). Set your preferred defaults in `.vscode/settings.json` under `manager.robot.condenseOutput` and `manager.robot.maxDocStringLength`.
 
 ### Running with arguments
-Run `pnpm manager-cli`, pick the workspace (or “All packages”), then select the `robot metadata` action. The helper walks you through:
+Run `pnpm manager-cli`, then choose `utils` -> `robot metadata`. The helper walks you through:
 
 1. Set the symbol kinds to capture (comma-separated list or `all`).
 2. Toggle `Only exported symbols`, adjust `Maximum columns`, `Condense output for compact JSON`, and `Docstring length limit`.

package/dist/docs/index.js

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, readdir, stat, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { rootDir } from '../helper-cli/env.js';
+import { runHelperCliMultiSelect } from '../helper-cli.js';
+import { colors, logGlobal } from '../utils/log.js';
+const DOCS_FOLDER_NAME = '.manager-docs';
+const DOCS_FALLBACK_FILE = 'docs-feature-output.txt';
+export function buildDocsClipboardText(files) {
+    const lines = [];
+    lines.push('# docs feature bundle');
+    lines.push(`files: ${files.length}`);
+    lines.push('');
+    for (const file of files) {
+        lines.push(`<<<FILE:${file.path}>>>`);
+        lines.push(file.content.replace(/\r\n/g, '\n'));
+        lines.push('<<<END FILE>>>');
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd() + '\n';
+}
+export function isLikelyBinary(buffer) {
+    if (buffer.length === 0)
+        return false;
+    const sample = buffer.subarray(0, Math.min(buffer.length, 8000));
+    for (const byte of sample) {
+        if (byte === 0x00)
+            return true;
+    }
+    return false;
+}
+function formatSize(size) {
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)} KB`;
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function collectDocsFiles(directory, baseDirectory = directory) {
+    const dirents = await readdir(directory, { withFileTypes: true });
+    const sorted = [...dirents].sort((a, b) => a.name.localeCompare(b.name));
+    const output = [];
+    for (const entry of sorted) {
+        const absolutePath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            output.push(...(await collectDocsFiles(absolutePath, baseDirectory)));
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const stats = await stat(absolutePath);
+        output.push({
+            absolutePath,
+            relativePath: path
+                .relative(baseDirectory, absolutePath)
+                .replace(/\\/g, '/'),
+            size: stats.size,
+        });
+    }
+    return output;
+}
+async function promptRescan(relativeDirectory) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = (await rl.question(colors.cyan(`Drop files into ${relativeDirectory}, then press Enter to rescan (or type "b" to go back): `)))
+            .trim()
+            .toLowerCase();
+        return !(answer === 'b' || answer === 'back' || answer === '0');
+    }
+    finally {
+        rl.close();
+    }
+}
+function openFolderCommands(absoluteDirectory) {
+    if (process.platform === 'darwin') {
+        return [{ command: 'open', args: [absoluteDirectory] }];
+    }
+    if (process.platform === 'win32') {
+        return [{ command: 'cmd', args: ['/c', 'start', '', absoluteDirectory] }];
+    }
+    return [
+        { command: 'xdg-open', args: [absoluteDirectory] },
+        { command: 'gio', args: ['open', absoluteDirectory] },
+    ];
+}
+function clipboardCommands() {
+    if (process.platform === 'darwin') {
+        return [{ command: 'pbcopy', args: [] }];
+    }
+    if (process.platform === 'win32') {
+        return [{ command: 'clip', args: [] }];
+    }
+    return [
+        { command: 'wl-copy', args: [] },
+        { command: 'xclip', args: ['-selection', 'clipboard'] },
+        { command: 'xsel', args: ['--clipboard', '--input'] },
+    ];
+}
+function launchCommand(command, args) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: rootDir,
+            stdio: 'ignore',
+            detached: true,
+        });
+        let settled = false;
+        child.once('error', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(false);
+        });
+        child.once('spawn', () => {
+            if (settled)
+                return;
+            settled = true;
+            child.unref();
+            resolve(true);
+        });
+    });
+}
+async function openDocsFolder(absoluteDirectory) {
+    for (const candidate of openFolderCommands(absoluteDirectory)) {
+        const launched = await launchCommand(candidate.command, candidate.args);
+        if (launched)
+            return true;
+    }
+    return false;
+}
+function tryClipboardCommand(command, args, text) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: rootDir,
+            stdio: ['pipe', 'ignore', 'ignore'],
+        });
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        child.once('error', () => done(false));
+        child.once('close', (code) => done(code === 0));
+        if (!child.stdin) {
+            done(false);
+            return;
+        }
+        child.stdin.on('error', () => done(false));
+        child.stdin.end(text);
+    });
+}
+async function copyToClipboard(text) {
+    for (const candidate of clipboardCommands()) {
+        const ok = await tryClipboardCommand(candidate.command, candidate.args, text);
+        if (ok)
+            return candidate;
+    }
+    return undefined;
+}
+async function loadClipboardFiles(selected) {
+    const files = [];
+    const skipped = [];
+    for (const file of selected) {
+        const buffer = await readFile(file.absolutePath);
+        if (isLikelyBinary(buffer)) {
+            skipped.push(file.relativePath);
+            continue;
+        }
+        files.push({
+            path: file.relativePath,
+            content: buffer.toString('utf8'),
+        });
+    }
+    return { files, skipped };
+}
+export async function runDocsFeature() {
+    const docsDirectory = path.join(rootDir, DOCS_FOLDER_NAME);
+    await mkdir(docsDirectory, { recursive: true });
+    const relativeDocsDirectory = path.relative(rootDir, docsDirectory).replace(/\\/g, '/') || '.';
+    logGlobal(`Docs feature folder: ${relativeDocsDirectory}`, colors.cyan);
+    const opened = await openDocsFolder(docsDirectory);
+    if (opened) {
+        logGlobal('Drop files into that folder, then return to this terminal.', colors.dim);
+    }
+    else {
+        logGlobal(`Could not auto-open ${relativeDocsDirectory}; add files manually and continue.`, colors.yellow);
+    }
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const files = await collectDocsFiles(docsDirectory);
+        if (files.length === 0) {
+            logGlobal(`No files found in ${relativeDocsDirectory}.`, colors.yellow);
+            const shouldRescan = await promptRescan(relativeDocsDirectory);
+            if (!shouldRescan)
+                return;
+            continue;
+        }
+        const selectedNames = await runHelperCliMultiSelect({
+            title: 'Docs feature (toggle files, press Space to copy)',
+            scripts: files.map((file) => ({
+                name: file.relativePath,
+                emoji: '📄',
+                description: formatSize(file.size),
+                handler: async () => { },
+            })),
+            argv: [],
+        });
+        if (!selectedNames)
+            return;
+        const selectedSet = new Set(selectedNames);
+        const selectedFiles = files.filter((file) => selectedSet.has(file.relativePath));
+        if (selectedFiles.length === 0) {
+            logGlobal('No files selected; nothing copied.', colors.yellow);
+            return;
+        }
+        const { files: clipboardFiles, skipped } = await loadClipboardFiles(selectedFiles);
+        if (!clipboardFiles.length) {
+            logGlobal('All selected files looked binary. Select text files instead.', colors.yellow);
+            continue;
+        }
+        const bundle = buildDocsClipboardText(clipboardFiles);
+        const clipboardCommand = await copyToClipboard(bundle);
+        if (clipboardCommand) {
+            logGlobal(`Copied ${clipboardFiles.length} files to clipboard via ${clipboardCommand.command}.`, colors.green);
+        }
+        else {
+            const fallbackPath = path.join(docsDirectory, DOCS_FALLBACK_FILE);
+            await writeFile(fallbackPath, bundle, 'utf8');
+            logGlobal(`Clipboard command not found. Wrote bundle to ${path.relative(rootDir, fallbackPath)}.`, colors.yellow);
+        }
+        if (skipped.length > 0) {
+            logGlobal(`Skipped ${skipped.length} binary files: ${skipped.join(', ')}`, colors.yellow);
+        }
+        return;
+    }
+}

package/dist/helper-cli/multi-select.js

@@ -0,0 +1,403 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { colors, getEntryColor } from './colors.js';
+import { pageHeading } from './display.js';
+import { BACK_KEY, buildVisibleOptions, NEXT_KEY, PAGE_SIZE, PREVIOUS_KEY, } from './pagination.js';
+import { findScriptEntry } from './scripts.js';
+function formatInteractiveLines(state, selectedIndex, selectedEntries, title, searchState) {
+    const heading = pageHeading(title, state.page, state.pageCount);
+    const lines = [heading];
+    lines.push(colors.dim(`Selected: ${selectedEntries.size}`));
+    if (searchState?.active) {
+        const queryLabel = searchState.query || '(type to filter)';
+        lines.push(colors.dim(`Search: ${queryLabel}`));
+    }
+    state.options.forEach((option, index) => {
+        const isSelectedRow = index === selectedIndex;
+        const pointer = isSelectedRow ? `${colors.green('➤')} ` : '';
+        const entryColorizer = option.type === 'entry' && option.entry.color
+            ? getEntryColor(option.entry)
+            : colors.cyan;
+        const numberLabelColorizer = isSelectedRow ? colors.green : entryColorizer;
+        const numberLabel = numberLabelColorizer(`${option.hotkey}`.padStart(2, ' '));
+        if (option.type === 'entry') {
+            const isChecked = selectedEntries.has(option.entry);
+            const checkbox = isChecked ? colors.green('[x]') : colors.dim('[ ]');
+            const labelColorizer = isSelectedRow ? colors.green : entryColorizer;
+            const label = labelColorizer(option.entry.displayName);
+            lines.push(`${pointer}${numberLabel}. ${checkbox} ${option.entry.emoji} ${label} ${colors.dim(option.entry.metaLabel)}`);
+            return;
+        }
+        const icon = option.action === 'back'
+            ? '↩️'
+            : option.action === 'previous'
+                ? '⬅️'
+                : '➡️';
+        const baseLabel = option.action === 'previous'
+            ? 'Previous page'
+            : option.action === 'next'
+                ? 'Next page'
+                : 'Back';
+        const navLabel = isSelectedRow && option.enabled
+            ? colors.green(baseLabel)
+            : option.enabled
+                ? baseLabel
+                : colors.dim(baseLabel);
+        lines.push(`${pointer}${numberLabel}. ${icon} ${navLabel}`);
+    });
+    if (searchState?.active && !searchState.hasResults) {
+        lines.push(colors.yellow('No scripts match your search.'));
+    }
+    lines.push('');
+    lines.push(colors.dim(`Use ↑/↓ (or j/k) to move, Enter or 1-${PAGE_SIZE} to toggle, Space to run selected, ${PREVIOUS_KEY} prev page, ${NEXT_KEY} next page, ${BACK_KEY} back, Type to filter, Esc/Ctrl+C to exit.`));
+    return lines;
+}
+function renderInteractiveList(lines, previousLineCount) {
+    const columns = process.stdout.columns ?? 80;
+    const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+    const visibleLength = (text) => {
+        const clean = text.replace(ansiRegex, '');
+        let length = 0;
+        for (const ch of clean) {
+            const code = ch.codePointAt(0) ?? 0;
+            length += code > 0xffff ? 2 : 1;
+        }
+        return length;
+    };
+    const nextLineCount = lines.reduce((total, line) => {
+        const len = visibleLength(line);
+        const wrapped = Math.max(1, Math.ceil(len / columns));
+        return total + wrapped;
+    }, 0);
+    if (previousLineCount > 0) {
+        process.stdout.write(`\x1b[${previousLineCount}A`);
+        process.stdout.write('\x1b[0J');
+    }
+    lines.forEach((line) => console.log(line));
+    return nextLineCount;
+}
+function renderReadlinePage(state, selectedEntries, title) {
+    console.log(pageHeading(title, state.page, state.pageCount));
+    console.log(colors.dim(`Selected: ${selectedEntries.size}`));
+    state.options.forEach((option) => {
+        const colorizer = option.type === 'entry' && option.entry.color
+            ? getEntryColor(option.entry)
+            : colors.cyan;
+        const numberLabel = colorizer(String(option.hotkey).padStart(2, ' '));
+        if (option.type === 'entry') {
+            const isChecked = selectedEntries.has(option.entry);
+            const checkbox = isChecked ? colors.green('[x]') : colors.dim('[ ]');
+            const label = option.entry.color
+                ? colorizer(option.entry.displayName)
+                : option.entry.displayName;
+            console.log(`  ${numberLabel} ${checkbox} ${option.entry.emoji} ${label} ${colors.dim(option.entry.metaLabel)}`);
+            return;
+        }
+        const icon = option.action === 'back'
+            ? '↩️'
+            : option.action === 'previous'
+                ? '⬅️'
+                : '➡️';
+        const label = option.action === 'previous'
+            ? 'Previous page'
+            : option.action === 'next'
+                ? 'Next page'
+                : 'Back';
+        const display = option.enabled ? label : colors.dim(label);
+        console.log(`  ${numberLabel} ${icon} ${display}`);
+    });
+    console.log(colors.dim(`Toggle by number/name. Type "run" (or "space") to continue, ${BACK_KEY} to go back.`));
+}
+async function promptWithReadline(entries, title) {
+    let page = 0;
+    const selectedEntries = new Set();
+    const rl = readline.createInterface({ input, output });
+    try {
+        while (true) {
+            const state = buildVisibleOptions(entries, page);
+            page = state.page;
+            renderReadlinePage(state, selectedEntries, title);
+            const answer = (await rl.question(colors.cyan('\nToggle option by number or name (run/space/0): '))).trim();
+            if (!answer)
+                continue;
+            const normalized = answer.toLowerCase();
+            if (normalized === 'run' || normalized === 'space') {
+                if (selectedEntries.size === 0) {
+                    console.log(colors.yellow('No entries selected. Toggle at least one.'));
+                    continue;
+                }
+                return entries.filter((entry) => selectedEntries.has(entry));
+            }
+            const numeric = Number.parseInt(answer, 10);
+            if (!Number.isNaN(numeric)) {
+                const option = state.options.find((opt) => opt.hotkey === numeric);
+                if (!option) {
+                    console.log(colors.yellow(`Unknown option "${answer}". Try again.`));
+                    continue;
+                }
+                if (option.type === 'entry') {
+                    if (selectedEntries.has(option.entry))
+                        selectedEntries.delete(option.entry);
+                    else
+                        selectedEntries.add(option.entry);
+                    continue;
+                }
+                if (option.action === 'back')
+                    return undefined;
+                if (option.action === 'previous') {
+                    if (option.enabled)
+                        page = Math.max(0, state.page - 1);
+                    else
+                        console.log(colors.yellow('No previous page.'));
+                    continue;
+                }
+                if (option.action === 'next') {
+                    if (option.enabled)
+                        page = Math.min(state.pageCount - 1, state.page + 1);
+                    else
+                        console.log(colors.yellow('No next page.'));
+                    continue;
+                }
+            }
+            const byName = findScriptEntry(entries, answer);
+            if (byName) {
+                if (selectedEntries.has(byName))
+                    selectedEntries.delete(byName);
+                else
+                    selectedEntries.add(byName);
+                continue;
+            }
+            console.log(colors.yellow(`Could not find "${answer}". Try again.`));
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function promptForScriptMultiSelect(entries, title) {
+    const supportsRawMode = typeof input.setRawMode === 'function' && input.isTTY;
+    if (!supportsRawMode) {
+        return promptWithReadline(entries, title);
+    }
+    const wasRaw = input.isRaw;
+    if (!wasRaw) {
+        input.setRawMode(true);
+        input.resume();
+    }
+    process.stdout.write('\x1b[?25l');
+    return new Promise((resolve) => {
+        const baseEntries = entries;
+        let filteredEntries = baseEntries;
+        const selectedEntries = new Set();
+        let selectedIndex = 0;
+        let renderedLines = 0;
+        let state = buildVisibleOptions(filteredEntries, 0);
+        let searchActive = false;
+        let searchQuery = '';
+        let pageBeforeSearch = 0;
+        let selectionBeforeSearch = 0;
+        const cleanup = () => {
+            if (renderedLines > 0) {
+                process.stdout.write(`\x1b[${renderedLines}A`);
+                process.stdout.write('\x1b[0J');
+                renderedLines = 0;
+            }
+            process.stdout.write('\x1b[?25h');
+            if (!wasRaw) {
+                input.setRawMode(false);
+                input.pause();
+            }
+            input.removeListener('data', onData);
+        };
+        const commitSelection = () => {
+            cleanup();
+            console.log();
+            resolve(baseEntries.filter((entry) => selectedEntries.has(entry)));
+        };
+        const commitBack = () => {
+            cleanup();
+            console.log();
+            resolve(undefined);
+        };
+        const rebuildState = (page) => {
+            state = buildVisibleOptions(filteredEntries, page);
+            selectedIndex = Math.min(selectedIndex, state.options.length - 1);
+            selectedIndex = Math.max(0, selectedIndex);
+        };
+        const render = () => {
+            const searchState = searchActive
+                ? {
+                    active: true,
+                    query: searchQuery.trim(),
+                    hasResults: filteredEntries.length > 0,
+                }
+                : undefined;
+            const lines = formatInteractiveLines(state, selectedIndex, selectedEntries, title, searchState);
+            renderedLines = renderInteractiveList(lines, renderedLines);
+        };
+        const setPage = (page) => {
+            rebuildState(page);
+            render();
+        };
+        const handleNav = (option) => {
+            if (option.action === 'back') {
+                commitBack();
+                return;
+            }
+            if (option.action === 'previous') {
+                if (option.enabled)
+                    setPage(state.page - 1);
+                else
+                    process.stdout.write('\x07');
+                return;
+            }
+            if (option.action === 'next') {
+                if (option.enabled)
+                    setPage(state.page + 1);
+                else
+                    process.stdout.write('\x07');
+            }
+        };
+        const toggleEntry = (entry) => {
+            if (selectedEntries.has(entry))
+                selectedEntries.delete(entry);
+            else
+                selectedEntries.add(entry);
+            render();
+        };
+        const activateOption = (option) => {
+            if (option.type === 'entry') {
+                toggleEntry(option.entry);
+                return;
+            }
+            handleNav(option);
+        };
+        const matchesSearchTerm = (entry, term) => {
+            const haystack = [
+                entry.displayName,
+                entry.metaLabel,
+                entry.script ?? '',
+                entry.description ?? '',
+            ]
+                .join(' ')
+                .toLowerCase();
+            return haystack.includes(term);
+        };
+        const applySearch = () => {
+            const normalized = searchQuery.trim().toLowerCase();
+            if (normalized.length > 0) {
+                filteredEntries = baseEntries.filter((entry) => matchesSearchTerm(entry, normalized));
+            }
+            else {
+                filteredEntries = baseEntries;
+            }
+            rebuildState(0);
+            selectedIndex = 0;
+            render();
+        };
+        const enterSearchMode = (initialQuery = '') => {
+            if (searchActive)
+                return;
+            pageBeforeSearch = state.page;
+            selectionBeforeSearch = selectedIndex;
+            searchActive = true;
+            searchQuery = initialQuery;
+            applySearch();
+        };
+        const exitSearchMode = () => {
+            if (!searchActive)
+                return;
+            searchActive = false;
+            searchQuery = '';
+            filteredEntries = baseEntries;
+            state = buildVisibleOptions(filteredEntries, pageBeforeSearch);
+            selectedIndex = Math.min(selectionBeforeSearch, state.options.length - 1);
+            render();
+        };
+        const onData = (buffer) => {
+            const isArrowUp = buffer.equals(Buffer.from([0x1b, 0x5b, 0x41]));
+            const isArrowDown = buffer.equals(Buffer.from([0x1b, 0x5b, 0x42]));
+            const isCtrlC = buffer.length === 1 && buffer[0] === 0x03;
+            const isEnter = buffer.length === 1 && (buffer[0] === 0x0d || buffer[0] === 0x0a);
+            const isEscape = buffer.length === 1 && buffer[0] === 0x1b;
+            const isBackspace = buffer.length === 1 && (buffer[0] === 0x7f || buffer[0] === 0x08);
+            const isSpace = buffer.length === 1 && buffer[0] === 0x20;
+            const ascii = buffer.length === 1 ? buffer[0] : undefined;
+            const isPrintable = ascii !== undefined && ascii >= 0x20 && ascii <= 0x7e;
+            const isDigit = ascii !== undefined && ascii >= 0x30 && ascii <= 0x39;
+            const typedChar = isPrintable && ascii !== undefined ? String.fromCharCode(ascii) : '';
+            if (isCtrlC) {
+                cleanup();
+                process.exit(1);
+            }
+            if (isEscape) {
+                if (searchActive) {
+                    exitSearchMode();
+                    return;
+                }
+                cleanup();
+                process.exit(1);
+            }
+            if (isArrowUp ||
+                (buffer.length === 1 && (buffer[0] === 0x6b || buffer[0] === 0x4b))) {
+                selectedIndex =
+                    (selectedIndex - 1 + state.options.length) % state.options.length;
+                render();
+                return;
+            }
+            if (isArrowDown ||
+                (buffer.length === 1 && (buffer[0] === 0x6a || buffer[0] === 0x4a))) {
+                selectedIndex = (selectedIndex + 1) % state.options.length;
+                render();
+                return;
+            }
+            if (isSpace) {
+                if (selectedEntries.size === 0) {
+                    process.stdout.write('\x07');
+                    return;
+                }
+                commitSelection();
+                return;
+            }
+            if (isEnter) {
+                const option = state.options[selectedIndex];
+                if (option)
+                    activateOption(option);
+                else
+                    process.stdout.write('\x07');
+                return;
+            }
+            if (searchActive) {
+                if (isBackspace) {
+                    if (searchQuery.length > 0) {
+                        searchQuery = searchQuery.slice(0, -1);
+                        applySearch();
+                    }
+                    return;
+                }
+                if (isPrintable) {
+                    searchQuery += typedChar;
+                    applySearch();
+                    return;
+                }
+                return;
+            }
+            if (isDigit && ascii !== undefined) {
+                const numericValue = ascii - 0x30;
+                const option = state.options.find((opt) => opt.hotkey === numericValue);
+                if (option)
+                    activateOption(option);
+                else
+                    process.stdout.write('\x07');
+                return;
+            }
+            if (isPrintable) {
+                enterSearchMode(typedChar);
+                return;
+            }
+            process.stdout.write('\x07');
+        };
+        input.on('data', onData);
+        render();
+    });
+}

package/dist/helper-cli/prompts.js

@@ -110,12 +110,28 @@ function formatInteractiveLines(state, selectedIndex, title, searchState) {
     return lines;
 }
 function renderInteractiveList(lines, previousLineCount) {
+    const columns = process.stdout.columns ?? 80;
+    const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g;
+    const visibleLength = (text) => {
+        const clean = text.replace(ansiRegex, '');
+        let length = 0;
+        for (const ch of clean) {
+            const code = ch.codePointAt(0) ?? 0;
+            length += code > 0xffff ? 2 : 1;
+        }
+        return length;
+    };
+    const nextLineCount = lines.reduce((total, line) => {
+        const len = visibleLength(line);
+        const wrapped = Math.max(1, Math.ceil(len / columns));
+        return total + wrapped;
+    }, 0);
     if (previousLineCount > 0) {
         process.stdout.write(`\x1b[${previousLineCount}A`);
         process.stdout.write('\x1b[0J');
     }
     lines.forEach((line) => console.log(line));
-    return lines.length;
+    return nextLineCount;
 }
 export async function promptForScript(entries, title) {
     const supportsRawMode = typeof input.setRawMode === 'function' && input.isTTY;

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/packages/manifest-utils.js

@@ -122,11 +122,6 @@ export function mergeManifestEntries(rootDir, inferred, overrides) {
             merged.push({ ...baseEntry, path: normalized });
         }
     }
-    normalizedOverrides.forEach((entry) => {
-        const name = entry.name || path.basename(entry.path) || 'package';
-        const color = entry.color ?? colorFromSeed(name);
-        merged.push({ name, path: entry.path, color });
-    });
     return merged;
 }
 export function colorFromSeed(seed) {

package/dist/publish.js

@@ -7,10 +7,12 @@ 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 { colors, logGlobal } from './utils/log.js';
 import { run } from './utils/run.js';
 const MANAGER_PACKAGE = '@emeryld/manager';
@@ -183,12 +185,54 @@ 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, 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: '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';
                     },
                 },
@@ -238,7 +282,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/manager",
-  "version": "1.4.15",
+  "version": "1.5.1",
   "description": "Interactive manager for pnpm monorepos (update/test/build/publish).",
   "license": "MIT",
   "type": "module",
@@ -23,13 +23,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "semver": "^7.7.3",
+    "semver": "^7.7.4",
     "ts-morph": "^27.0.2",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.3.0"
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@types/node": "^20.17.0",
+    "@types/node": "^20.19.33",
     "@types/semver": "^7.7.1",
     "cross-env": "^7.0.3"
   },