@erbium-app/cli 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -2
- package/dist/index.js +2017 -0
- package/package.json +50 -4
package/README.md
CHANGED
|
@@ -1,3 +1,77 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Erbium CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Install source-owned Erbium UI in a TypeScript React project configured with shadcn. Use Node 22.18 or later and Git for comparisons and merges.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
bunx --package @erbium-app/cli erbium init
|
|
7
|
+
bunx --package @erbium-app/cli erbium search button
|
|
8
|
+
bunx --package @erbium-app/cli erbium docs button
|
|
9
|
+
bunx --package @erbium-app/cli erbium add styles button
|
|
10
|
+
bunx --package @erbium-app/cli erbium status
|
|
11
|
+
bunx --package @erbium-app/cli erbium diff button
|
|
12
|
+
bunx --package @erbium-app/cli erbium update --dry-run
|
|
13
|
+
bunx --package @erbium-app/cli erbium update
|
|
14
|
+
bunx --package @erbium-app/cli erbium check
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
By default, overlapping edits abort the whole operation before any source, baseline, lock or dependency changes. For `add` and `update`, choose one of these options when you need to resolve the overlap explicitly.
|
|
18
|
+
|
|
19
|
+
- `--conflict-markers` writes Git conflict markers into tracked files and records the incoming revision as the baseline. Resolve the marked sections and run `erbium check`. The check fails while markers remain.
|
|
20
|
+
- `--overwrite` replaces selected files with the registry version, including existing unmanaged files and missing tracked files. Use `erbium update <item> --overwrite` to reset a tracked item even when its revision is already current.
|
|
21
|
+
|
|
22
|
+
Both options support `--dry-run`. The write plan still checks file ownership, shared targets and dependency constraints.
|
|
23
|
+
|
|
24
|
+
Use `add --skip-install` or `update --skip-install` if you manage package dependencies separately. The command reports what to install, and `check` verifies the declarations afterward.
|
|
25
|
+
|
|
26
|
+
Use `adopt` with items already installed by shadcn. Their source must match a published revision. Use `history <item>` and `adopt <item> --at <commit>` for an older release. Managed installs use the TypeScript path aliases and explicit targets used by Erbium's two registries. Use shadcn for other registries and framework-specific shadcn transforms.
|
|
27
|
+
|
|
28
|
+
Commit the installed source and `.erbium/lock.json` and `.erbium/bases/`. The lock tracks item revisions, file owners, and exact upstream file hashes. The baseline files make the exact installed bytes available offline. If a baseline file is missing, Erbium checks the working file and local Git history. Upstream diffs and merges can also reconstruct the baseline from a verified registry snapshot. Changes in unrelated project code are outside the scope of `check`.
|
|
29
|
+
|
|
30
|
+
Use `--cwd` to select a project and `--json` for scripting. An interrupted file operation can be resumed by removing the empty `.erbium/operation` directory after confirming the process stopped, then rerunning the write command. Keep the pending journal until recovery succeeds.
|
|
31
|
+
|
|
32
|
+
The docs build publishes both ordinary shadcn catalogs and the managed registry at `/r/erbium`. Production builds require a full Git checkout to reproduce snapshots from the registry's first-parent history.
|
|
33
|
+
|
|
34
|
+
## Custom registries
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
erbium init --registry ../registry/dist/registry/r/erbium
|
|
38
|
+
erbium init --registry https://ui.example.com/r/erbium \
|
|
39
|
+
--header 'Authorization: Bearer ${ERBIUM_INTERNAL_TOKEN}' \
|
|
40
|
+
--header 'X-Project: ${ERBIUM_PROJECT_ID}'
|
|
41
|
+
erbium add button
|
|
42
|
+
erbium docs button
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`init --registry` saves the managed registry in `erbium.config.json` at the project root. You can edit that file directly. Its `registry` field accepts a path, an HTTP(S) URL, or an object with `url` and `headers`. Relative paths resolve from `--cwd`. Pass `--registry` on a command to override the saved location for that invocation. With a saved registry, `docs` opens registry item documentation. Use `docs --site https://ui.erbium.app` to read public guides.
|
|
46
|
+
|
|
47
|
+
Every configured header value must contain a `${VARIABLE}` placeholder. Erbium reads the process environment first, then `.env.local`, then `.env`. Missing values fail before the request. Configured headers apply only to the saved endpoint, require HTTPS or loopback HTTP, and disable redirects. For older setups, `ERBIUM_REGISTRY_TOKEN` remains a bearer-token fallback for custom HTTP(S) registries without configured headers.
|
|
48
|
+
|
|
49
|
+
The shadcn namespace entries in `components.json` are configured independently. `init` preserves existing entries and fills in any missing public Erbium defaults. For shadcn installs from a custom host, point the entries to that host’s `/r/ui/{name}.json` and `/r/examples/{name}.json` endpoints and configure [shadcn authentication](https://ui.shadcn.com/docs/registry/authentication) there.
|
|
50
|
+
|
|
51
|
+
## Registry tooling
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
erbium registry build ./registry.json --examples ./examples/registry.json --history --out dist/registry
|
|
55
|
+
erbium registry validate --registry dist/registry/r/erbium
|
|
56
|
+
erbium registry serve dist/registry
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Build takes Shadcn catalogs with inlined file content and emits Shadcn item endpoints at `/r/ui` and `/r/examples` alongside the managed registry at `/r/erbium`. It checks that relative and Erbium registry imports resolve to files shipped by the item or its registry dependencies. Use `--history` with committed catalogs in a full Git checkout to publish first-parent revisions for `history` and `adopt --at`. Without it, the build publishes the current snapshots. Run `erbium docs <item> --registry <location>` to read an item’s metadata, dependencies and source without the public docs site.
|
|
60
|
+
|
|
61
|
+
Open the output directory's `index.html` through a static host or `registry serve` to browse items, source and revisions. The build also generates an agent index at `llms.txt`. Serve listens on loopback for local testing.
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
erbium usage --offline --json > usage.json
|
|
65
|
+
erbium check --json > verify.json
|
|
66
|
+
erbium registry build registry.json --storybook storybook-static --usage usage.json --verify verify.json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- `--storybook` copies a built Storybook with `index.json` and `iframe.html` to `storybook/`. Item pages link to stories whose `<item>.stories.*` filename matches the item name, preferring the Default story when available.
|
|
70
|
+
- `--usage` publishes the output of `erbium usage --json` at `usage.json`. Usage reports include project and file paths, so keep the site private when the report covers private code.
|
|
71
|
+
- `--verify` publishes the output of `erbium check --json` at `verify.json`, including failed checks when supplied. The build validates the report format and publishes the supplied results.
|
|
72
|
+
|
|
73
|
+
Pass `--no-site` to write only the managed and shadcn registry files. Rebuilding removes optional site artifacts when their flags are omitted.
|
|
74
|
+
|
|
75
|
+
`usage --offline --json` scans a local Git checkout. Its report lists direct importers and consuming workspaces reachable through local imports and resolvable workspace packages. Run it after installing workspace dependencies so package exports can be resolved. Use `--repo <git-url>` to scan a temporary checkout of another repository through its committed files and TypeScript aliases. Use `--github <organization>` to scan the repositories visible to your authenticated GitHub CLI. Remote scans use your configured Git credentials and clone one repository at a time.
|
|
76
|
+
|
|
77
|
+
[CLI guide](https://ui.erbium.app/docs/cli) · [Installation guide](https://ui.erbium.app/docs/installation)
|