monoregen

Monorepo index regenerator. Walk an org's repos (local + GitHub), reconcile metadata into one canonical picture, emit it as a public-facing README, a Claude Code plugin marketplace JSON, a diagnostic terminal report, and back into the config itself.

Built on nushell. Single config file (orgmap.toml) is the source of truth; everything else is derived.

What it produces

Given an orgmap.toml describing your org's GitHub identity, workspace layout, and per-project overrides, monoregen will (re)generate:

Subcommand	Output
write	README.md projects section + marketplace.json + manifest snapshot
report	terminal diagnostic — every project enumerated with status icons
sync	rewrites the [sections] block in orgmap.toml to inscribe every repo
git	per-repo branch / ahead-behind / dirty / age summary
preview	live: watchexec regen + gh-markdown-preview server with auto-reload
watch	regen-only watcher (no preview server)
edit	$EDITOR on the config
config	pretty-print the parsed config

Install

Clone anywhere, then either:

# Direct invocation
nu /path/to/monoregen/monoregen.nu <subcommand> --config /path/to/orgmap.toml

# Or alias it for convenience
alias monoregen='nu /path/to/monoregen/monoregen.nu'
monoregen write --config ./orgmap.toml

Quick start

cp examples/orgmap.toml ./orgmap.toml
$EDITOR orgmap.toml                       # set [scan].gh_org and [output] paths
monoregen write   --config ./orgmap.toml  # populate artifacts
monoregen report  --config ./orgmap.toml  # see what was produced
monoregen preview --config ./orgmap.toml  # live edit ↔ render loop

Configuration shape

See examples/orgmap.toml for an annotated reference. The schema in brief:

Block	Purpose
[scan]	GitHub org identity, default section, scan roots, blacklist
[output]	Paths the writers touch (README, marketplace JSON, manifest, gh cache)
[features]	Opt-in toggles (plugin_marketplace, git_state_report)
[workspaces.<key>]	One per workspace — display name, emoji, preamble, optional install command
[sections]	[sections.<workspace>] = ["proj", ...] — bulk section assignment, sync-managed
[stages]	Lifecycle badges per project (research / beta / certified / hazard-low / hazard-high / archived; numeric aliases 1/2/3/-1/-2 supported)
[overrides.<name>]	Per-project escapes — description, tagline, display_name, stage, section

Resolution chains

Field	Chain (first match wins)
description	[overrides.<name>].description → <project>/.git-meta → gh repo description (when gh_fallback=true) → empty cell
section	[overrides.<name>].section → <project>/.git-meta.section → [sections.<workspace>] array → on-disk workspace → [scan].default_section
stage	[overrides.<name>].stage → [sections.<workspace>] inline prefix → <project>/.git-meta.stage → [stages.<level>] array → null

Inline stage prefixes in [sections]

Section entries support an optional <stage>: prefix to assign a lifecycle stage alongside the section listing — handy for one-off editorial decisions where stage and section are co-curated. Both numeric aliases and canonical names work:

[sections]
repo-kit = [
  "transq",             # bare name — stage falls through to other tiers
  "3:compoet",          # stage = certified
  "research:foom",      # stage = research
  "-2:hazardous-fork",  # stage = hazard-high
]

The prefix survives monoregen sync round-trips and overrides any value in [stages.<level>] or <project>/.git-meta. [overrides.<name>].stage still wins (dedicated escape hatch).

Public-render gate

A project appears in the rendered markdown only when it's announced via either:

• explicit orgmap declaration ([sections] or [overrides]), OR
• an upstream GitHub repo

Projects that are neither in the config nor on GitHub are "shadow" projects — visible in the diagnostic report (struck through), never in the public index.

Architecture

Three responsibility tiers + one side door:

monoregen.nu              entry — flag parsing + subcommand dispatch

picture/                  TIER 3 — build the canonical record
  orgmap.nu               load + normalize-stage + workspace-order
  gh.nu                   list-repos + fetch-manifest + cache
  scan.nu                 fs walk + synth-upstream + .git-meta + remote probe
  resolve.nu              desc/section/stage/tags chains
  build.nu                orchestrator: assembles everything into one Picture record

emit/                     TIER 2 — each consumes Picture, emits one artifact
  readme.nu               projects + harness sections, splice into target README
  marketplace.nu          marketplace.json
  report.nu               --report terminal output
  sync.nu                 rewrite [sections] block in orgmap.toml
  manifest.nu             snapshot/load/diff (change tracking)

git_state/                SIDE DOOR — separate small pipeline+emitter for `git`
  probe.nu                per-repo state probe
  render.nu               print-git-report

command/                  TIER 1 — thin wirers
  write.nu / report.nu / sync.nu / git.nu / preview.nu / watch.nu / edit.nu / config.nu

ansi.nu                   cross-cutting: chip rendering, padding-aware coloring

Caching

monoregen write does a fresh gh repo list + per-repo plugin manifest scan (~3-5s on 50 repos). Subsequent runs can use --cached to skip the network and read from [output].gh_cache instead — drops re-render to <1s.

monoregen preview automatically primes the cache on startup, then runs every file-watch re-render with --cached for snappy live-reload.

To force a refresh: run any non---cached invocation (e.g. monoregen write).

Roadmap

• Autodiscovery: monoregen invoked with no --config walks up parent directories until it finds an orgmap.toml — drops the path arg in most workflows. Deferred; CLI shape designed to slot it in non-breakingly.
• Multiple output targets: emit several READMEs from one config (e.g. one per workspace as standalone landing pages).
• Generic emitters: support emitting JSON-LD, OPML, or other formats besides README markdown.

License

MIT — see LICENSE.