@emeryld/manager 1.0.1 → 1.2.0

package/README.md

@@ -15,38 +15,95 @@ Dev dependency built for Codex agents: scan a pnpm workspace, scaffold RRRoutes
 - **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, 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.
+- `back` → return to package selection. When a single package is chosen, its `package.json` scripts also appear as runnable entries.
+
+## Format checker configuration
+
+`manager-cli` ships with a format checker action that respects defaults in `.vscode/settings.json` under the `manager.formatChecker` key. Define:
+
+| setting | description |
+| --- | --- |
+| `maxFunctionLength` | allowed lines per function |
+| `maxIndentationDepth` | indentation spaces before warning |
+| `maxFunctionsPerFile` | functions allowed in a file |
+| `maxComponentsPerFile` | component abstractions allowed |
+| `maxFileLength` | total lines per file |
+| `maxDuplicateLineOccurrences` | times a similar line can repeat |
+| `minDuplicateLines` | minimum consecutive lines required for repetition warnings |
+| `exportOnly` | limit function/component checks to exported symbols |
+| `indentationWidth` | spaces to count per tab when evaluating indentation depth |
+
+Each run also prompts for overrides, so you can tweak targets without editing the file.
+The override prompt now lists every limit at once; you can move with ↑/↓, type to replace the highlighted value, Backspace to erase characters, and press Enter when the values validate before confirming.
+You can also decide where the report lands: the manager will ask whether to stream the violations to the console or dump them into a temporary file that is opened in your editor (no repo files are modified).
+
+## Format checker scan CLI
+- **Usage**: `pnpm manager-cli scan [flags]` scans the workspace without interactive prompts while honoring defaults in `.vscode/settings.json` under `manager.formatChecker`.
+- **Flags**: override any limit via the table below or run `pnpm manager-cli scan --help`/`-h` to print the same guidance.
+
+| Flag | Description |
+| --- | --- |
+| `--max-function-length <number>` | Maximum lines per function before a violation is reported. |
+| `--max-indentation-depth <number>` | Maximum indentation depth (spaces) that the scanner tolerates. |
+| `--max-functions-per-file <number>` | Maximum number of functions allowed in a source file. |
+| `--max-components-per-file <number>` | Maximum component abstractions permitted per file. |
+| `--max-file-length <number>` | Maximum total lines in a file before the file-length rule triggers. |
+| `--max-duplicate-line-occurrences <number>` | Maximum times a similar line may repeat before it counts as duplication. |
+| `--min-duplicate-lines <number>` | Minimum consecutive duplicate lines needed to trigger the duplicate check (set to `0` to skip the requirement). |
+| `--indentation-width <number>` | Number of spaces counted per tab when measuring indentation depth. |
+| `--export-only <true|false>` | When `true`, component/function counts only consider exported symbols. |
+| `--reporting-mode <group|file>` | Choose `group` (summary by violation type) or `file` (per-file entries). |
+| `--export-mode <console|editor>` | Choose `console` to print violations in the terminal or `editor` to write them to a temporary file and open it in your default editor. Defaults to `console`. |
+- **Purpose**: give Codex agents, CI pipelines, and automation deterministic scans that print the same violation summaries as the interactive action.
+- **Output**: prints `Format checker violations:` followed by grouped or per-file buckets (with severity, snippets, and location references); when no violations occur you get `Format checker found no violations.` and `Workspace meets the configured format limits.` Colors mirror the interactive report to keep results easy to scan.
+
+## Robot metadata
+
+The `robot metadata` action now starts with the same interactive settings screen as the format checker: pick which kinds of symbols to include, decide whether to limit the scan to exported declarations, and adjust the column width. Use ↑/↓ to move between rows, type new values (comma-separated lists for the kinds), and press Enter once the validation message disappears.
+
+Before the extraction runs you can also choose how to consume the results. The default `console` stream prints the JSON into your terminal, while `editor` writes the report to a temporary file (non-saved) and tries to open it in your editor via your configured `$EDITOR`, `code`, or the OS `open/xdg-open` helpers.
 
 ## Non-interactive release (Codex/CI)
-- Syntax: `pnpm manager-cli <pkg|all> --non-interactive [publish flags]`
-- Required: the selection (`<pkg>` or `all`) **and** one of `--bump <type>`, `--sync <version>`, or `--noop` (skip version change but still publish/tag).
-- Flags:
-  - `--non-interactive`, `--ci`, `--yes`, `-y` → auto-confirm prompts.
-  - `--bump <patch|minor|major|prepatch|preminor|premajor|prerelease>` → bump versions (pre* keeps/previews prerelease ids).
-  - `--sync <version>` → set all selected packages to an exact version.
-  - `--tag <dist-tag>` → publish with a custom npm dist-tag (default inferred from prerelease suffix).
-  - `--dry-run` → pass through to `pnpm publish --dry-run`.
-  - `--provenance` → enable provenance on publish.
-  - `--noop` → skip version change but still tag/publish current versions.
-- Behavior: commits any existing changes before running (prompting for a message), requires registry auth (`pnpm whoami`), and tags/pushes after publish.
-
-## Scaffolding packages
-- Interactive: `pnpm manager-cli create` → prompts for template, path, package name, contract (for server/client), and client kind (for client/fullstack). Uses arrow keys/digits when the terminal supports raw mode.
-- Headless (Codex/CI) flags:
-  - `--list`, `-l` → show available templates.
-  - `--describe`, `-d <variant>` → print scripts/files/notes for a template.
-  - `--variant`, `-v <id>` → pick a template without a prompt (ids below).
-  - `--dir`, `--path`, `-p <path>` → target directory.
-  - `--name`, `-n <pkg>` → package name (defaults to basename of `--dir`).
-  - `--contract <pkg>` → contract import for server/client templates.
-  - `--client-kind <vite-react|expo-react-native>` → choose client stack (client/fullstack).
-  - `--reset` → delete the target directory before scaffolding.
-  - `--skip-install` / `--skip-build` → skip post-create install/build.
-  - `--help`, `-h` → print help.
-- After effects: ensures the target directory exists (warns if non-empty, or wipes it when `--reset`), writes shared tooling files (tsconfig, workspace helpers), scaffolds the template, runs `pnpm install`, then builds the new package and its workspace deps (fallbacks: full workspace build, then package-only build). Each scaffolded package includes its own README with variant-specific scripts.
+- **Syntax**: `pnpm manager-cli <pkg|all> --non-interactive [publish flags]`
+- **Requirements**: provide the selection (`<pkg>` or `all`) and one of `--bump <type>`, `--sync <version>`, or `--noop` (skip the version change but still tag/publish). Use `--non-interactive`, `--ci`, `--yes`, or `-y` interchangeably to answer every prompt in the affirmative.
+- **Behavior**: commits any existing changes (prompting for a message), checks registry auth (`pnpm whoami`), runs `pnpm publish` (filtered when possible), tags, and pushes after a successful release.
+- **Flags**:
+
+| Flag | Description |
+| --- | --- |
+| `--non-interactive`, `--ci`, `--yes`, `-y` | Auto-respond “yes” to every prompt. |
+| `--bump <patch|minor|major|prepatch|preminor|premajor|prerelease>` | Bump versions (pre* keeps or previews prerelease tags). |
+| `--sync <version>` | Set all selected packages to the exact semver you pass. |
+| `--noop` | Skip the version bump but still tag/publish the current versions. |
+| `--tag <dist-tag>` | Publish with a custom npm dist-tag (defaults to prerelease suffix inference). |
+| `--dry-run` | Forward `--dry-run` to `pnpm publish`. |
+| `--provenance` | Enable npm provenance metadata when publishing. |
+
+`--bump`, `--sync`, or `--noop` are mandatory in non-interactive mode. Optional flags like `--tag`, `--dry-run`, and `--provenance` layer additional behavior on top of the release pipeline.
+
+## Create package CLI
+- Interactive: `pnpm manager-cli create` prompts for template, path, package name, contract (for server/client), and client kind (when applicable). The menu accepts ↑/↓/j/k navigation, digits, and arrow keys when raw mode is available.
+- Headless usage: `pnpm manager-cli templates` is a shorthand for `create --list`. Any other flag combination described below will skip prompts and scaffold directly.
+
+| Flag | Description |
+| --- | --- |
+| `--list`, `-l` | List every available template (`rrr-contract`, `rrr-server`, etc.) with their default directories and summaries. |
+| `--describe <variant>`, `-d` | Print the scripts, key files, and notes for a specific template before scaffolding. |
+| `--variant <id>`, `-v` | Choose a template by ID, partial label, or friendly name without hitting the prompts. |
+| `--dir`, `--path`, `-p <path>` | Target directory for the new package (defaults to the variant’s default). |
+| `--name`, `-n <pkg>` | Package name inside `package.json`; defaults to the basename of `--dir`. |
+| `--contract <pkg>` | Contract import to wire into server/client templates. |
+| `--client-kind <vite-react|expo-react-native>` | Pick the client stack for client-friendly templates. |
+| `--reset` | Delete the existing target directory before scaffolding (refuses to reset the workspace root). |
+| `--skip-install` | Do not run `pnpm install` after scaffolding. |
+| `--skip-build` | Skip the post-scaffold build step (only meaningful when not skipping install). |
+| `--help`, `-h` | Show the help text above. |
+
+After scaffolding, helper tooling (tsconfig, workspace helpers, etc.) is ensured, the template is written, and a build/install attempt runs unless skipped. Each generated package ships with its own README explaining variant-specific scripts.
 
 ## Templates at a glance
 | id | default dir | summary | key files |
@@ -69,6 +126,8 @@ Use `pnpm manager-cli create --describe <variant>` to print the scripts, key fil
   `pnpm manager-cli @scope/api --non-interactive --bump minor --tag next`
 - Publish everything with a synced version:  
   `pnpm manager-cli all --non-interactive --sync 1.2.3 --provenance`
+- Run the format checker scan headlessly:  
+  `pnpm manager-cli scan --max-function-length 90 --reporting-mode file`
 
 ## Notes
 - Helper scripts register the bundled `ts-node/esm` loader so the CLI works even when dependencies are hoisted.

package/dist/cli/interactive-settings.js

@@ -0,0 +1,191 @@
+import { stdin as input, stdout as output } from 'node:process';
+import { colors } from '../utils/log.js';
+const DEFAULT_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.',
+];
+export async function promptInteractiveSettings({ title, descriptors, initial, instructions, validate, }) {
+    const supportsInteractive = typeof input.setRawMode === 'function' && input.isTTY;
+    if (!supportsInteractive) {
+        throw new Error('Interactive mode is not available in this environment.');
+    }
+    return new Promise((resolve) => {
+        const wasRaw = input.isRaw;
+        if (!wasRaw) {
+            input.setRawMode(true);
+            input.resume();
+        }
+        output.write('\x1b[?25l');
+        const state = {
+            selectedIndex: 0,
+            editingIndex: null,
+            editBuffer: '',
+            justFocused: false,
+            errorMessage: '',
+            renderedLines: 0,
+        };
+        const settings = { ...initial };
+        const writableSettings = settings;
+        const cleanup = () => {
+            if (state.renderedLines > 0) {
+                output.write(`\x1b[${state.renderedLines}A`);
+                output.write('\x1b[0J');
+                state.renderedLines = 0;
+            }
+            output.write('\x1b[?25h');
+            if (!wasRaw) {
+                input.setRawMode(false);
+                input.pause();
+            }
+            input.off('data', onData);
+        };
+        const finalize = () => {
+            cleanup();
+            console.log();
+            resolve(settings);
+        };
+        const render = () => {
+            const lines = buildInteractiveLines(title, descriptors, settings, state, instructions ?? DEFAULT_INSTRUCTIONS);
+            if (state.renderedLines > 0) {
+                output.write(`\x1b[${state.renderedLines}A`);
+                output.write('\x1b[0J');
+            }
+            lines.forEach((line) => console.log(line));
+            state.renderedLines = lines.length;
+        };
+        const startEditing = () => {
+            state.editingIndex = state.selectedIndex;
+            state.editBuffer = '';
+            state.justFocused = true;
+            state.errorMessage = '';
+        };
+        const moveSelection = (delta) => {
+            state.selectedIndex =
+                (state.selectedIndex + delta + descriptors.length) % descriptors.length;
+            state.editingIndex = null;
+            state.editBuffer = '';
+            state.justFocused = false;
+            state.errorMessage = '';
+            render();
+        };
+        const commitEdit = () => {
+            if (state.editingIndex === null)
+                return;
+            const descriptor = descriptors[state.editingIndex];
+            const parsed = descriptor.parse(state.editBuffer);
+            if (parsed.error) {
+                state.errorMessage = parsed.error;
+                process.stdout.write('\x07');
+                render();
+                return;
+            }
+            if (parsed.value !== undefined) {
+                writableSettings[descriptor.key] = parsed.value;
+            }
+            state.editingIndex = null;
+            state.editBuffer = '';
+            state.justFocused = false;
+            state.errorMessage = '';
+            render();
+        };
+        const handlePrintable = (typedChar) => {
+            if (state.editingIndex !== state.selectedIndex) {
+                startEditing();
+            }
+            if (state.justFocused) {
+                state.editBuffer = typedChar;
+                state.justFocused = false;
+            }
+            else {
+                state.editBuffer += typedChar;
+            }
+            render();
+        };
+        const handleBackspace = () => {
+            if (state.editingIndex !== state.selectedIndex) {
+                startEditing();
+                state.justFocused = false;
+            }
+            if (state.editBuffer.length > 0) {
+                state.editBuffer = state.editBuffer.slice(0, -1);
+                render();
+                return;
+            }
+            process.stdout.write('\x07');
+        };
+        const onData = (buffer) => {
+            const ascii = buffer.length === 1 ? buffer[0] : undefined;
+            const isPrintable = ascii !== undefined && ascii >= 0x20 && ascii <= 0x7e;
+            const typedChar = isPrintable && ascii !== undefined ? String.fromCharCode(ascii) : '';
+            const isArrowUp = buffer.equals(Buffer.from([0x1b, 0x5b, 0x41]));
+            const isArrowDown = buffer.equals(Buffer.from([0x1b, 0x5b, 0x42]));
+            const isEnter = buffer.length === 1 && (buffer[0] === 0x0d || buffer[0] === 0x0a);
+            const isEscape = buffer.length === 1 && buffer[0] === 0x1b;
+            const isCtrlC = buffer.length === 1 && buffer[0] === 0x03;
+            const isBackspace = buffer.length === 1 && (buffer[0] === 0x7f || buffer[0] === 0x08);
+            if (isCtrlC || isEscape) {
+                cleanup();
+                process.exit(1);
+            }
+            if (isArrowUp) {
+                moveSelection(-1);
+                return;
+            }
+            if (isArrowDown) {
+                moveSelection(1);
+                return;
+            }
+            if (isEnter) {
+                if (state.editingIndex === state.selectedIndex) {
+                    commitEdit();
+                    return;
+                }
+                const validation = validate?.(settings);
+                if (validation) {
+                    state.errorMessage = validation;
+                    process.stdout.write('\x07');
+                    render();
+                    return;
+                }
+                finalize();
+                return;
+            }
+            if (isBackspace) {
+                handleBackspace();
+                return;
+            }
+            if (isPrintable && typedChar) {
+                handlePrintable(typedChar);
+                return;
+            }
+            process.stdout.write('\x07');
+        };
+        input.on('data', onData);
+        render();
+    });
+}
+function buildInteractiveLines(title, descriptors, settings, state, instructions) {
+    const heading = colors.bold(title);
+    const lines = [heading, ''];
+    descriptors.forEach((descriptor, index) => {
+        const isSelected = index === state.selectedIndex;
+        const pointer = isSelected ? colors.green('➤') : '  ';
+        const label = descriptor.unit
+            ? `${descriptor.label} (${descriptor.unit})`
+            : descriptor.label;
+        const isActive = state.editingIndex === index;
+        const baseValue = descriptor.format(settings[descriptor.key]);
+        const displayValue = isActive
+            ? colors.yellow(state.editBuffer.length > 0 ? state.editBuffer : baseValue)
+            : colors.magenta(baseValue);
+        const labelColor = isSelected ? colors.green : colors.cyan;
+        const line = `${pointer} ${labelColor(label)}: ${displayValue}`;
+        lines.push(line);
+    });
+    lines.push('');
+    instructions.forEach((instruction) => lines.push(colors.dim(instruction)));
+    if (state.errorMessage) {
+        lines.push(colors.red(`⚠ ${state.errorMessage}`));
+    }
+    return lines;
+}

package/dist/create-package/shared.js

@@ -135,9 +135,11 @@ export function vscodeSettings() {
         'editor.defaultFormatter': 'esbenp.prettier-vscode',
         'editor.formatOnSave': true,
         'editor.codeActionsOnSave': {
-            'source.fixAll.eslint': true,
+            'source.fixAll.eslint': 'always',
+            'source.organizeImports': true,
         },
         'eslint.useFlatConfig': true,
+        'eslint.format.enable': true,
         'eslint.validate': ['typescript', 'javascript'],
         'files.eol': '\n',
         'prettier.requireConfig': true,

package/dist/create-package/variants/client/client_vite_r.js

@@ -19,9 +19,13 @@ VITE_SOCKET_PATH=/socket.io
 function vitePackageJson(name, contractName, includePrepare) {
     const dependencies = {
         '@emeryld/rrroutes-client': '^2.5.3',
+        '@emotion/react': '^11.12.1',
+        '@emotion/styled': '^11.12.1',
+        '@mui/material': '^5.17.1',
         '@tanstack/react-query': '^5.90.12',
         react: '^18.3.1',
         'react-dom': '^18.3.1',
+        recharts: '^2.7.2',
         'socket.io-client': '^4.8.3',
         zod: '^4.2.1',
     };
@@ -72,21 +76,57 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 function appTsx() {
     return `import React from 'react'
 import { QueryClientProvider } from '@tanstack/react-query'
+import { ThemeProvider } from '@mui/material/styles'
+import CssBaseline from '@mui/material/CssBaseline'
+import Container from '@mui/material/Container'
 import { queryClient } from './lib/queryClient'
 import { AppSocketProvider } from './lib/socket'
 import { HealthPage } from './pages/HealthPage'
+import theme from './theme'
 
 export default function App() {
   return (
-    <QueryClientProvider client={queryClient}>
-      <AppSocketProvider>
-        <HealthPage />
-      </AppSocketProvider>
-    </QueryClientProvider>
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      <QueryClientProvider client={queryClient}>
+        <AppSocketProvider>
+          <Container component="main" maxWidth="lg">
+            <HealthPage />
+          </Container>
+        </AppSocketProvider>
+      </QueryClientProvider>
+    </ThemeProvider>
   )
 }
 `;
 }
+function themeFile() {
+    return `import { createTheme } from '@mui/material/styles'
+
+const theme = createTheme({
+  palette: {
+    mode: 'light',
+    primary: { main: '#2563eb' },
+    secondary: { main: '#f97316' },
+    background: {
+      default: '#f5f7ff',
+      paper: '#ffffff',
+    },
+  },
+  typography: {
+    fontFamily: ['Inter', 'Segoe UI', 'system-ui', 'sans-serif'].join(', '),
+    button: {
+      textTransform: 'none',
+    },
+  },
+  shape: {
+    borderRadius: 12,
+  },
+})
+
+export default theme
+`;
+}
 const STYLES = `:root {
   font-family: 'Inter', system-ui, -apple-system, sans-serif;
   color: #0b1021;
@@ -168,6 +208,11 @@ textarea {
   min-height: 160px;
   white-space: pre-line;
 }
+
+.chart-card .chart-container {
+  height: 220px;
+  width: 100%;
+}
 `;
 function queryClient(contractImport) {
     if (contractImport) {
@@ -347,6 +392,14 @@ export function useSocketConnection() {
 }
 function healthPage(contractImport) {
     return `import React from 'react'
+import {
+  Bar,
+  BarChart,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts'
 import { healthGet, healthPost, hasContract } from '../lib/queryClient'
 import { roomMeta, useSocketClient, useSocketConnection, socketReady } from '../lib/socket'
 
@@ -369,6 +422,18 @@ export function HealthPage() {
   const socket = useSocketClient()
   const { logs, push, clear } = useLogs()
 
+  const chartData = React.useMemo(
+    () => [
+      { name: 'Logs', value: logs.length },
+      { name: 'Socket ready', value: socketReady ? 1 : 0 },
+      {
+        name: 'HTTP errors',
+        value: Number(Boolean(httpGet.error || httpPost.error)),
+      },
+    ],
+    [logs.length, socketReady, httpGet.error, httpPost.error],
+  )
+
   useSocketConnection({
     event: 'health:connected',
     rooms: ['health'],
@@ -502,6 +567,20 @@ export function HealthPage() {
             {logs.length === 0 ? 'No messages yet' : logs.join('\\n')}
           </div>
         </div>
+
+        <div className="card chart-card">
+          <h2>Live state</h2>
+          <div className="chart-container">
+            <ResponsiveContainer width="100%" height="100%">
+              <BarChart data={chartData}>
+                <XAxis dataKey="name" />
+                <YAxis />
+                <Tooltip />
+                <Bar dataKey="value" fill="#2563eb" radius={[4, 4, 0, 0]} />
+              </BarChart>
+            </ResponsiveContainer>
+          </div>
+        </div>
       </div>
     </div>
   )
@@ -542,6 +621,7 @@ export async function scaffoldViteReactClient(ctx) {
         'vite.config.ts': viteConfig(),
         'src/main.tsx': MAIN_TSX,
         'src/App.tsx': appTsx(),
+        'src/theme.ts': themeFile(),
         'src/lib/queryClient.ts': queryClient(ctx.contractName),
         'src/lib/socket.tsx': socketProvider(ctx.contractName),
         'src/pages/HealthPage.tsx': healthPage(ctx.contractName),

package/dist/format-checker/cli/options.js

@@ -0,0 +1,133 @@
+import { colors } from '../../utils/log.js';
+import { EXPORT_MODES } from '../../utils/export.js';
+import { parseBooleanInput, parsePositiveInteger, parseReportingModeInput, } from './settings.js';
+export const SCAN_FLAG_DEFINITIONS = [
+    {
+        flag: '--max-function-length',
+        description: 'Maximum function length (lines).',
+        key: 'maxFunctionLength',
+        parser: (value) => parseNumberFlag(value, '--max-function-length'),
+    },
+    {
+        flag: '--max-indentation-depth',
+        description: 'Maximum indentation depth (spaces).',
+        key: 'maxIndentationDepth',
+        parser: (value) => parseNumberFlag(value, '--max-indentation-depth'),
+    },
+    {
+        flag: '--max-functions-per-file',
+        description: 'Maximum functions per file.',
+        key: 'maxFunctionsPerFile',
+        parser: (value) => parseNumberFlag(value, '--max-functions-per-file'),
+    },
+    {
+        flag: '--max-components-per-file',
+        description: 'Maximum components per file.',
+        key: 'maxComponentsPerFile',
+        parser: (value) => parseNumberFlag(value, '--max-components-per-file'),
+    },
+    {
+        flag: '--max-file-length',
+        description: 'Maximum total lines per file.',
+        key: 'maxFileLength',
+        parser: (value) => parseNumberFlag(value, '--max-file-length'),
+    },
+    {
+        flag: '--max-duplicate-line-occurrences',
+        description: 'Allowed repeated/similar line occurrences.',
+        key: 'maxDuplicateLineOccurrences',
+        parser: (value) => parseNumberFlag(value, '--max-duplicate-line-occurrences'),
+    },
+    {
+        flag: '--min-duplicate-lines',
+        description: 'Minimum repeated lines (0 disables minimum).',
+        key: 'minDuplicateLines',
+        parser: (value) => parseNumberFlag(value, '--min-duplicate-lines', { allowZero: true }),
+    },
+    {
+        flag: '--export-only',
+        description: 'Limit checks to exported symbols (true|false).',
+        key: 'exportOnly',
+        parser: (value) => parseBooleanFlag(value),
+    },
+    {
+        flag: '--indentation-width',
+        description: 'Spaces counted per tab when measuring indentation.',
+        key: 'indentationWidth',
+        parser: (value) => parseNumberFlag(value, '--indentation-width'),
+    },
+    {
+        flag: '--reporting-mode',
+        description: 'How violations are grouped (group|file).',
+        key: 'reportingMode',
+        parser: (value) => parseReportingModeFlag(value),
+    },
+];
+export function parseScanCliArgs(argv) {
+    const entries = [];
+    let exportMode = 'console';
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--help' || token === '-h') {
+            const overrides = Object.fromEntries(entries);
+            return { overrides, help: true, exportMode };
+        }
+        if (token === '--export-mode') {
+            const rawValue = argv[++i];
+            if (!rawValue) {
+                throw new Error('Flag "--export-mode" expects a value.');
+            }
+            const normalized = rawValue.toLowerCase();
+            if (!EXPORT_MODES.includes(normalized)) {
+                throw new Error(`Flag "--export-mode" expects one of ${EXPORT_MODES.join(', ')}.`);
+            }
+            exportMode = normalized;
+            continue;
+        }
+        const definition = SCAN_FLAG_DEFINITIONS.find((def) => def.flag === token);
+        if (!definition) {
+            throw new Error(`Unknown scan option "${token}". Use "pnpm manager-cli scan --help".`);
+        }
+        const rawValue = argv[++i];
+        if (!rawValue) {
+            throw new Error(`Flag "${token}" expects a value.`);
+        }
+        entries.push([
+            definition.key,
+            definition.parser(rawValue),
+        ]);
+    }
+    const overrides = Object.fromEntries(entries);
+    return { overrides, help: false, exportMode };
+}
+export function printScanUsage() {
+    console.log(colors.bold('Usage: pnpm manager-cli scan [flags]'));
+    console.log(colors.dim('Run the format checker scan without interactive prompts. Defaults respect .vscode/settings.json (manager.formatChecker).'));
+    console.log('');
+    console.log(`${colors.cyan('--export-mode <console|editor>')}\tWhere to print scan results. Defaults to console.`);
+    console.log('');
+    SCAN_FLAG_DEFINITIONS.forEach((definition) => {
+        console.log(`${colors.cyan(definition.flag)}\t${definition.description}`);
+    });
+    console.log('');
+    console.log(colors.dim('Use --help or -h to show this message.'));
+}
+function parseNumberFlag(value, flag, options) {
+    const parsed = parsePositiveInteger(value, options);
+    if (parsed === undefined) {
+        throw new Error(`Flag "${flag}" expects a ${options?.allowZero ? 'non-negative' : 'positive'} integer.`);
+    }
+    return parsed;
+}
+function parseBooleanFlag(raw) {
+    const parsed = parseBooleanInput(raw);
+    if (parsed.error)
+        throw new Error(parsed.error);
+    return parsed.value;
+}
+function parseReportingModeFlag(raw) {
+    const result = parseReportingModeInput(raw);
+    if (result.error)
+        throw new Error(result.error);
+    return result.value;
+}