Skip to main content

Guides

Ouro UI at a company

Ouro HX is copy-in source: a component is yours to change, which is why an agent can fix what it ships. That suits one team. For a company of many teams it raises questions about ownership: who owns the version the teams get, and who decides when it moves. This guide covers what Ouro ships for them: a registry your company owns, updates that wait for a person, and a report of which apps are behind or have edited what. An npm package isn't offered, because it would take away the edit-in-place model that the checks rely on.

A registry your company owns

Mirror Ouro's registry at a release you have reviewed into a shadcn registry under your own namespace, such as @acme/button. Teams install from the mirror, and one reviewed pull request on the mirror moves the teams that install from it.

git clone --depth 1 https://github.com/ourostack/ouro-ui
TAG=vX.Y.Z   # the release you reviewed, from https://github.com/ourostack/ouro-ui/releases
node ouro-ui/scripts/mirror/mirror.mjs --tag "$TAG" --namespace @acme --out ./acme-registry

The script reads the tag's registry.json, which only a release tag has, and the files it lists, from GitHub at that tag.mirror-read Pass --source <folder> to read them from a checkout of the release instead. It writes:

  • r/<item>.json, one per item, with the contents of its files inside and its dependencies on other Ouro items pointed at your namespace (@acme/lib-cn), in the shape the public @ouro namespace has.mirror-shape
  • r/registry.json, the index.
  • mirror.json, which records the source tag of the items, the sha256 of each source file, and the sha256 of the item's own JSON.mirror-record The file hash is the one an install record holds, so a team's record and the mirror agree on what a file was.

Host the r/ folder anywhere that serves files, and point teams at it once in their components.json:

{ "registries": { "@acme": "https://registry.acme.example/r/{name}.json" } }

Then npx shadcn@latest add @acme/ouro-base once per app and npx shadcn@latest add @acme/dialog for a component, as the installing guide does for @ouro.

To move to a new release, run the script again with its tag and review the pull request: an item whose source changed has a different hash in mirror.json, and one that did not has the same. --check builds the mirror in memory and lists each item whose file under --out is missing, changed or extra, for the mirror repository's own CI.mirror-check The script stops on a registry that is not a release's, on the public @ouro namespace and on an --out folder that is not a mirror.mirror-refuses

An app that installs from your mirror should not also let Ouro Current move it to a release your company has not reviewed. Leave its install record out of Current's reach in the app's .github/ouro-current.json:

{ "ignore": [".github/ouro-hx-installed.json"] }

A pin file named there stays where it is.ignore

Updates that wait for a person

Ouro Current opens its update pull request with auto-merge on. For a repository whose governance wants a person to approve a change, name a review team in .github/ouro-current.json:

{ "review": { "team": "design-system" } }

Current then opens the update with auto-merge off and asks that team to review it, when the pull request opens and after a push.review The team is a slug in the organisation that owns the repository, or "acme/design-system"; one outside it fails that repository's run with the fix.review-bad Current's README lists the rest of what it reads from that file.

Who is behind, and who has edited what

The drift report reads an app's Ouro HX install record, .github/ouro-hx-installed.json: the tag the app installed from, and the sha256 of the source of the files it installed. For the apps you give it, it lists the Ouro items the app has, the release it is on, and which of their files differ from that release's source.drift-states

node ouro-ui/scripts/drift/drift.mjs ../spoonjoy ../recipes --latest "$TAG"

The report takes the registry source at the record's tag, rewrites it as the shadcn CLI does for the app's components.json aliases, and compares it with the file in the checkout. A file is released when they are the same, edited when they differ, missing when the app no longer has it, and unlisted when that release's registry no longer lists it.drift-states An app whose record names an older release than --latest (or, without it, GitHub's newest release) is behind.drift-behind --json prints the report as JSON, and --strict exits 1 when an app is behind, has a file that is not as released, or has no install record, so a company's CI can fail on drift.drift-cli

The report uses what an install leaves in an app: the install record, which Ouro Current also reads, and components.json. An app without a record can write one from a checkout of Ouro UI that has the tag, with node scripts/current/local-update.mjs <app> --record <tag>.record The report covers Ouro HX items; Ouro Current's --dry-run --only <owner/repo> also reports a repository's pins of the core and Apple releases.dry-run

Claim sources