monorepo-script-commands

Monorepo script commands (Bun + Ink)

When to use

• New multi-subcommand script (for example bun tools/scripts/foo/index.tsx wired as bun run foo from root package.json).
• Long-running flows that should show per-step progress without spamming logs.
• Mixing Ink UI with child process stdout (install, turbo, biome).

Layout

Keep one canonical step list per flow; do not fork “quiet” vs “interactive” logic beyond wrapping.

Arg parsing

• Use parseArgs from node:util with args: [...rest], strict: true, and typed options.
• Bun.argv.slice(2) → sub = argv[0], rest = argv.slice(1) for flags after the subcommand.

Step progress (Ink)

1. Define getXxxSteps(...): readonly StepProgressStep[] using a closure object (for example state) so each step’s run can depend on prior results.

2. Wrap UI in StepProgressApp from tools/scripts/shared/step-progress.tsx with a child component that does:

   const resolveSteps = useCallback(() => getXxxSteps(deps), [deps]);

3. Completed lines: Ink <Static> so finished steps stay fixed; live row = spinner + dim current label (marginTop when there is at least one completed line). Do not use full-terminal height unless a footer must pin to the bottom of the screen.

4. Subprocess output: render(..., { stdout: process.stderr }) so tool output stays on stdout and does not fight the Ink buffer. Prefer renderAndExit from tools/scripts/shared/render-and-exit.tsx (defaults to stdout: process.stderr, waitUntilExit, unmount, printCliError + process.exit(1) on failure — message only, no Bun stack trace).

5. Top-level failures: use printCliErrorAndExit from tools/scripts/shared/format-cli-error.ts in index.tsx .catch() handlers; never console.error(error) with an Error instance.