navig-menu

An AI-first menu builder for any project. Walk into a repo, run one command, and navig-menu auto-detects its stack, package manager, scripts, workspace shape, frameworks and services — then builds a premium interactive terminal menu with a factual banner and safe, one-keystroke actions. No per-project menu.js to hand-write.

npx navig-menu

That's it — run it in any project root, zero install, nothing to configure. It also runs as a single self-contained binary (no Node), and integrates into NAVIG as navig menu.

──────────────────────────────────────────────────────────
│  🌌  S C H E M A  ·  developer console
──────────────────────────────────────────────────────────
│  🔭  webapp     https://localhost   TLS ✓
│  ⚡  api        http://localhost:3001
──────────────────────────────────────────────────────────
│  🧩  stack      pnpm · Next.js · Cloudflare · Stripe
│  🌿  branch     main  @a1b2c3d  · clean
│  🖥  node       v22 · linux x64
──────────────────────────────────────────────────────────
│  📊  42 scripts · 3 packages · 2 services
──────────────────────────────────────────────────────────

✦ What would you like to do? …

⚡ DEVELOPMENT 4 ──────────────────────
> ◆ Dev                            pnpm run dev
  ◆ Preview                        pnpm run preview
🧪 QUALITY 9 ──────────────────────────
  ◆ Test                           pnpm run test
  ◆ Lint                           pnpm run lint
🧰 UTILITIES 3 ────────────────────────
  ⚙ Settings                       accent · layout · plugins · …
  ★ About                          navig.run · @miztizm
  ⏻ Quit

↑/↓ move · enter run · / search · s settings · c customize · q quit

Prefer ASCII? It's the default (renders identically on every terminal). Switch to emoji/unicode, the compact console banner, or the tree (nested filesystem) / list / categories layouts live in Settings (s).

Install / run

npx navig-menu          # zero-install, in any project root
# or, with the global binary:
npm i -g navig-menu && navig-menu
# or, inside NAVIG:
navig menu

Want pnpm menu / npm run menu to open it? Run navig-menu generate — it writes .navig/menu.json and adds a single "menu": "npx navig-menu" script when package.json has no menu script yet. It always adds "menu:navig": "npx navig-menu" too, so generated menus have one stable command across projects. If a project already has a custom menu script, it is preserved and only menu:navig is added.

Commands

Command	What it does
navig-menu	Open the menu (auto-builds on first run).
navig-menu build [--ai]	(Re)generate .navig/menu.json from detection. --ai enriches via NAVIG / emits an authoring prompt.
navig-menu generate	Create the same pro .navig/menu.json contract and add npm run menu (gen and create are aliases).
navig-menu list	Print a static Schema-style menu preview (ls and preview are aliases).
navig-menu scan	Detect + report (refresh cache), no UI.
navig-menu setup	Guided config; offers the menu npm script.
navig-menu doctor	Diagnose environment + detection.
navig-menu run <action>	Run a canonical action (dev/build/test/…) or any script id.
navig-menu --json	Emit the machine manifest (no UI) — for tooling / CI.

Flags: --cwd <path> · --deep · --plain · --yes · --relay · --host <name> · --no-cache.

How it works

sources (detect, no execution)  →  manifest (evidence + confidence)  →  builder (heuristic + AI)
   project scripts                   .navig/menu.cache.json (gitignored)     canonical map + risk
                                                                                     │
runner (local | NAVIG relay)  ←  UI framework (banner + flow + DSL)  ←  .navig/menu.json (versioned)

• Evidence-based detection. Every framework/service carries an evidence[] array and a confidence (explicit/detected/inferred/unknown). It never reads .env values — only filenames and variable names.
• Canonical actions, not rewritten scripts. dev/build/test/… are mapped onto whatever your repo actually calls them. Your package.json scripts are never rewritten.
• Safety tiers. safe runs directly; confirm asks once; dangerous (deploy/reset/clean/ destructive-db) needs a typed confirmation that --yes cannot bypass. Commands run as an argv array — never a shell string.
• Human/AI overrides. Edit .navig/menu.json (or let an AI author it). Re-builds merge and preserve your edits.
• Pro generator. navig-menu generate writes a rich contract with canonical action objects, descriptions, risk tiers, lifecycle-script hiding, UI defaults, and an audit of mapped versus preserved entries. It also adds the safe zero-install menu package script if missing. navig-menu generate --json previews the file without writing.
• Stable pro TUI. The menu is a fixed-height command palette with recents, grouped sections, type-to-search, details, and refresh. Keyboard movement is clamped to the visible viewport, so short terminals do not corrupt selection state.
• Static preview. navig-menu list --plain prints the same banner, sections, selected-command footer, and scroll affordances without opening raw TTY mode. Use it for screenshots, CI checks, or quick command discovery.
• Local history. Recently launched commands are stored in .navig/menu.recent.json and ignored by git. The versioned .navig/menu.json can tune UI behavior with ui.recentLimit, ui.showDescriptions, ui.showCommandHints, and ui.footer.

See docs/ for the DSL, the override schema, and the AI-authoring contract.

Plugins

The menu is extensible. A plugin can change the banner (add lines/phrases), overwrite text (title/tagline/prompt), add sections + commands, claim/relabel your scripts, add settings, and expose actions with handlers. Two tiers: declarative (a safe JSON/YAML file in .navig/plugins/) and programmatic (definePlugin({...}) for dynamic work). Plugins are discovered from built-ins, .navig/plugins/, and npm (navig-menu-plugin-*), and toggled from the in-menu Plugins manager (key p). A bundled store plugin auto-activates on projects with store:*/steam:* scripts and shows a Store · <product>: <N> downloads banner line. Full guide: docs/plugins.md.

Plugins run only in the model/menu phase — never during the pure detection scan, so the cached manifest stays execution-free and secret-free.

About

Press a for the About screen — tool version, website (navig.run), author (github.com/miztizm), and the loaded plugins.

License

MIT