@barqjs/ui-cli 0.0.0-stage → 0.2.0-next.1
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/LICENSE +21 -0
- package/README.md +195 -2
- package/dist/build-C65qsG0d.js +136 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.js +1761 -0
- package/package.json +63 -4
- package/src/add.ts +124 -0
- package/src/build.ts +167 -0
- package/src/config.ts +76 -0
- package/src/diff.ts +111 -0
- package/src/files.ts +147 -0
- package/src/index.ts +989 -0
- package/src/project.ts +115 -0
- package/src/registry.ts +196 -0
- package/src/schema.ts +392 -0
- package/src/theme.ts +227 -0
- package/src/tty.ts +133 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Salama Ashoush
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,196 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @barqjs/ui-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Copy barq's components into your project, and keep them in sync with the
|
|
4
|
+
registry they came from. The components are not a package: their source lives in
|
|
5
|
+
[`packages/ui`](../ui#readme), and this CLI is the only way they reach an app.
|
|
6
|
+
|
|
7
|
+
A component you add is your code: it lands in your repository, it goes through
|
|
8
|
+
your review, and you edit it. That is shadcn/ui's idea, and the commands follow
|
|
9
|
+
the `shadcn` CLI's. What is different is that this CLI knows which files you
|
|
10
|
+
have edited, so `sync` can take an upstream change without taking your changes
|
|
11
|
+
back.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
Nothing to install. Run it with `bunx` (or `npx`) in the project; the binary is
|
|
16
|
+
`barq-ui`:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
bunx @barqjs/ui-cli init
|
|
20
|
+
bunx @barqjs/ui-cli add button card dialog
|
|
21
|
+
bunx @barqjs/ui-cli add dashboard-01
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Items come from the registry built from `packages/ui`, read from this
|
|
25
|
+
repository at the tag the CLI was released under, so a CLI version always writes
|
|
26
|
+
the components of the same release. `BARQ_UI_REGISTRY` replaces that default
|
|
27
|
+
with any `{name}` pattern, for a fork, a mirror or a local build.
|
|
28
|
+
|
|
29
|
+
## Commands
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
barq-ui init set up components.json, the theme and the base styles
|
|
33
|
+
barq-ui add <name...> add components and blocks, with whatever they need
|
|
34
|
+
barq-ui diff [name...] what the registry has that your copy does not
|
|
35
|
+
barq-ui sync [name...] take the registry's version, keeping your edits
|
|
36
|
+
barq-ui list what the registry offers
|
|
37
|
+
barq-ui search <query> find items by name, description or category
|
|
38
|
+
barq-ui view <name...> print items as the registry serves them
|
|
39
|
+
barq-ui info what this project is set up with
|
|
40
|
+
barq-ui theme <name> change the colour theme
|
|
41
|
+
barq-ui style <name> change the component style
|
|
42
|
+
barq-ui build <dir> turn a directory of components into a registry
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`--cwd <dir>` runs against another directory, `--yes` takes every default,
|
|
46
|
+
`--overwrite` replaces a file you have edited, and `--json` makes `search` and
|
|
47
|
+
`info` print JSON. Piped into a script there is nowhere to prompt, so every
|
|
48
|
+
question takes its default and `--yes` is unnecessary in CI. `barq-ui --help`
|
|
49
|
+
lists every flag.
|
|
50
|
+
|
|
51
|
+
## `add`
|
|
52
|
+
|
|
53
|
+
`add` writes the item and everything its `registryDependencies` name, then
|
|
54
|
+
installs the npm packages those files import that the project does not have.
|
|
55
|
+
The package manager is the one whose lockfile is nearest, at or above the
|
|
56
|
+
project: `bun.lock`, `pnpm-lock.yaml`, `yarn.lock` or `package-lock.json`.
|
|
57
|
+
`--no-install` prints the command instead of running it.
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
barq-ui add --all every ui component the registry has
|
|
61
|
+
barq-ui add dialog --dry-run what would be written, and nothing written
|
|
62
|
+
barq-ui add dialog --diff what would change in the files you have
|
|
63
|
+
barq-ui add dialog --view the files as they would be written
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`--diff=<file>` and `--view=<file>` narrow either to the files whose path ends
|
|
67
|
+
that way.
|
|
68
|
+
|
|
69
|
+
## Blocks and charts
|
|
70
|
+
|
|
71
|
+
The registry carries the site's blocks (`dashboard-01`, `sidebar-01` to
|
|
72
|
+
`sidebar-16`, `login-01` to `login-05`, `signup-01` to `signup-05`) and its
|
|
73
|
+
charts, one item per family (`chart-area`, `chart-bar`, `chart-line`,
|
|
74
|
+
`chart-pie`, `chart-radar`, `chart-radial`, `chart-tooltip`). A block lands in
|
|
75
|
+
`blocks/` under `paths.components`, a chart family in `charts/`, and each brings
|
|
76
|
+
the ui components it is built from. `barq-ui search sidebar` lists what matches.
|
|
77
|
+
|
|
78
|
+
## `sync`, and why it is not `add` again
|
|
79
|
+
|
|
80
|
+
`init` and `add` record a hash per file in `components.json`. That is the whole
|
|
81
|
+
mechanism, and it is what lets `sync` tell three cases apart:
|
|
82
|
+
|
|
83
|
+
- Identical to the registry's: nothing happens, and nothing is said.
|
|
84
|
+
- Untouched since it was added: replaced.
|
|
85
|
+
- Edited: shown as a diff and **kept**, unless you pass `--overwrite`.
|
|
86
|
+
|
|
87
|
+
shadcn's `diff` cannot make that distinction (it has no record of what it
|
|
88
|
+
wrote), so it shows you the difference and leaves the applying to you. Owning
|
|
89
|
+
the code means your edit wins by default; taking it back silently would be the
|
|
90
|
+
tool taking the ownership back.
|
|
91
|
+
|
|
92
|
+
## `components.json`
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"paths": {
|
|
97
|
+
"ui": "src/components/ui",
|
|
98
|
+
"lib": "src/components/lib",
|
|
99
|
+
"theme": "src/components/theme",
|
|
100
|
+
"components": "src/components",
|
|
101
|
+
"hooks": "src/hooks"
|
|
102
|
+
},
|
|
103
|
+
"theme": { "base": "neutral", "accent": "blue", "radius": "0.625rem" },
|
|
104
|
+
"reset": true,
|
|
105
|
+
"items": {}
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**`registry`** is where items without a scope come from: a URL or a path with
|
|
110
|
+
`{name}` in it, which `init --registry` writes. Left out, it is the registry of
|
|
111
|
+
the CLI's own release.
|
|
112
|
+
|
|
113
|
+
**`registries`** names more registries by scope, and an item from one is
|
|
114
|
+
addressed as `@scope/name`:
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"registries": {
|
|
119
|
+
"@acme": "https://acme.example.com/r/{name}.json",
|
|
120
|
+
"@private": {
|
|
121
|
+
"url": "https://registry.example.com/{name}.json",
|
|
122
|
+
"headers": { "Authorization": "Bearer ${API_TOKEN}" }
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`${NAME}` is read from the environment, so a token is never written into the
|
|
129
|
+
file. A pattern that is not a URL is a path from the project root, which is how
|
|
130
|
+
the output of `build` is used before anything serves it. A bare name in an
|
|
131
|
+
item's `registryDependencies` always means the project's own registry.
|
|
132
|
+
|
|
133
|
+
**`paths`** is where files go. A component's own imports are RELATIVE and are
|
|
134
|
+
recomputed against where the files actually land, so any layout works and none
|
|
135
|
+
of it depends on a `tsconfig` alias. `ui`, `lib`, `theme` and `hooks` each take
|
|
136
|
+
the files of their type by name. Blocks, components and examples keep the path
|
|
137
|
+
their registry gave them, under `components`. A `registry:page` or
|
|
138
|
+
`registry:file` names its own `target` from the project root, and a path that
|
|
139
|
+
would leave the project is refused before anything is written.
|
|
140
|
+
|
|
141
|
+
**`theme`** is a base colour theme, optionally an accent over it, and the
|
|
142
|
+
radius. `init` asks for all three from a list, and writes them into a `theme.ts`
|
|
143
|
+
the barq compiler folds into a stylesheet, so an application that picks its
|
|
144
|
+
theme once pays nothing at run time.
|
|
145
|
+
|
|
146
|
+
**`theme.style`** is one of shadcn's eight component styles, and it is opt-in:
|
|
147
|
+
with none, you get this package's own look, which is shadcn's classic registry
|
|
148
|
+
transcribed. Choosing one copies that stylesheet into your project, because a
|
|
149
|
+
style is 180 KB and you picked one.
|
|
150
|
+
|
|
151
|
+
Each of the four has a flag, so `init` is scriptable: `--style`, `--theme`,
|
|
152
|
+
`--accent`, `--radius`, and `--dark <selector>` for the class dark mode is asked
|
|
153
|
+
for by, or `--dark media` to follow the operating system. `--path <dir>` moves
|
|
154
|
+
the components, and `--no-reset` leaves out the CSS reset. A name none of the
|
|
155
|
+
themes has stops `init` before it writes anything, and says which names exist.
|
|
156
|
+
`barq-ui theme <name>` and `barq-ui style <name>` change either one later.
|
|
157
|
+
|
|
158
|
+
## A registry of your own
|
|
159
|
+
|
|
160
|
+
`build` reads a directory of components and writes the JSON a registry serves:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
barq-ui build ./src/components
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
The rules are the ones `@barqjs/ui` builds its own with. A file's bare imports
|
|
167
|
+
are its npm dependencies; its relative imports are the items it needs. The
|
|
168
|
+
directory a file is in is its type: `lib`, `theme`, `hooks`, `blocks`,
|
|
169
|
+
`components`, `examples`, and `ui` for anything else. A directory under `blocks`
|
|
170
|
+
is one item with every file in it. Serve the result and point a
|
|
171
|
+
`components.json` at it, as the registry or as one of several:
|
|
172
|
+
|
|
173
|
+
```json
|
|
174
|
+
{ "registry": "https://acme.example.com/r/{name}.json" }
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
An item may also carry `devDependencies`, `categories`, `meta`, and `cssVars`
|
|
178
|
+
and `css`. The last two are written into the project's `theme.ts`: `cssVars`
|
|
179
|
+
as tokens under `light`, `dark` or `theme` (the root, in either mode), `css` as
|
|
180
|
+
rules after them. They are recorded in `components.json` too, so `barq-ui theme`
|
|
181
|
+
keeps them when it rewrites the file.
|
|
182
|
+
|
|
183
|
+
## No dependencies
|
|
184
|
+
|
|
185
|
+
The argument parsing, the prompts, the diff and the schema checks are each
|
|
186
|
+
smaller than the library that would do them. A tool someone runs once to write
|
|
187
|
+
eight files should not download eight of its own first.
|
|
188
|
+
|
|
189
|
+
The diff is Myers' shortest-edit-script over lines, which is the algorithm
|
|
190
|
+
`git diff` uses and the right one here: two versions of a component are nearly
|
|
191
|
+
identical, and Myers' work is proportional to the size of the difference rather
|
|
192
|
+
than to the size of the files.
|
|
193
|
+
|
|
194
|
+
## License
|
|
195
|
+
|
|
196
|
+
MIT
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { dirname, join, relative, resolve } from "node:path";
|
|
3
|
+
// src/build.ts
|
|
4
|
+
/**
|
|
5
|
+
* `build`: a directory of components, as a registry someone else can `add`.
|
|
6
|
+
*
|
|
7
|
+
* The same rules `@barqjs/ui` builds its own with — a file's bare imports are
|
|
8
|
+
* its npm dependencies, its relative imports are the items it needs — so a
|
|
9
|
+
* registry of your own works the same way and can depend on this one's items by
|
|
10
|
+
* name.
|
|
11
|
+
*
|
|
12
|
+
* The directory a file is in says what it is: `lib`, `theme`, `hooks`,
|
|
13
|
+
* `blocks`, `components` and `examples` are each their own type, and anything
|
|
14
|
+
* else is a `ui` component.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* `import … from "x"`, `export … from "x"` and a bare `import "x"`.
|
|
18
|
+
*
|
|
19
|
+
* `from` is required rather than "the first quoted string on the line", which
|
|
20
|
+
* is what this used to be: `export type ButtonVariant = "default" | …` then
|
|
21
|
+
* declared a dependency on a package called `default`.
|
|
22
|
+
*
|
|
23
|
+
* What stands between the keyword and `from` is an import CLAUSE and nothing
|
|
24
|
+
* else — names, braces, commas, `*`, whitespace. Matching "anything up to the
|
|
25
|
+
* end of the line" instead missed every import long enough to be wrapped, and
|
|
26
|
+
* that is most of them: `context-menu.tsx` declared no dependency on
|
|
27
|
+
* `@barqjs/aria` and none on `dropdown-menu`, so `add context-menu` wrote a
|
|
28
|
+
* file that imports a component the project does not have.
|
|
29
|
+
*/
|
|
30
|
+
const IMPORT = /(?:^|\n)\s*(?:import|export)\s+(?:type\s+)?[\w*{}\s,$]+?\s*\bfrom\s*["']([^"']+)["']|(?:^|\n)\s*import\s+["']([^"']+)["']/g;
|
|
31
|
+
function specifiersIn(source) {
|
|
32
|
+
const out = [];
|
|
33
|
+
for (const match of source.matchAll(IMPORT)) {
|
|
34
|
+
const specifier = match[1] ?? match[2];
|
|
35
|
+
if (specifier !== void 0) out.push(specifier);
|
|
36
|
+
}
|
|
37
|
+
return out;
|
|
38
|
+
}
|
|
39
|
+
/** `@barqjs/lucide/icons/check` -> `@barqjs/lucide`. What you install. */
|
|
40
|
+
function packageOf(specifier) {
|
|
41
|
+
const parts = specifier.split("/");
|
|
42
|
+
return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0] ?? specifier;
|
|
43
|
+
}
|
|
44
|
+
function titleOf(name) {
|
|
45
|
+
return name.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
|
|
46
|
+
}
|
|
47
|
+
/** Every `.ts`/`.tsx` under `directory`, excluding tests, as paths relative to it. */
|
|
48
|
+
function sourcesIn(directory, prefix = "") {
|
|
49
|
+
const out = [];
|
|
50
|
+
for (const entry of readdirSync(directory, { withFileTypes: true }).toSorted((a, b) => a.name.localeCompare(b.name))) {
|
|
51
|
+
const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
|
|
52
|
+
if (entry.isDirectory()) out.push(...sourcesIn(join(directory, entry.name), path));
|
|
53
|
+
else if (/\.tsx?$/.test(entry.name) && !entry.name.includes(".test.")) out.push(path);
|
|
54
|
+
}
|
|
55
|
+
return out;
|
|
56
|
+
}
|
|
57
|
+
const DIRECTORIES = {
|
|
58
|
+
lib: "registry:lib",
|
|
59
|
+
theme: "registry:theme",
|
|
60
|
+
hooks: "registry:hook",
|
|
61
|
+
blocks: "registry:block",
|
|
62
|
+
components: "registry:component",
|
|
63
|
+
examples: "registry:example"
|
|
64
|
+
};
|
|
65
|
+
function typeOf(path) {
|
|
66
|
+
const first = path.includes("/") ? path.split("/")[0] ?? "" : "";
|
|
67
|
+
return DIRECTORIES[first] ?? "registry:ui";
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* The item a file belongs to.
|
|
71
|
+
*
|
|
72
|
+
* A file is an item of its own, named for the file. A DIRECTORY under `blocks`
|
|
73
|
+
* is one item with everything in it, because that is what a block is: a page
|
|
74
|
+
* and the components only that page uses.
|
|
75
|
+
*/
|
|
76
|
+
function ownerOf(path) {
|
|
77
|
+
const parts = path.split("/");
|
|
78
|
+
if (parts[0] === "blocks" && parts.length > 2) return parts[1];
|
|
79
|
+
return (parts.at(-1) ?? path).replace(/\.tsx?$/, "");
|
|
80
|
+
}
|
|
81
|
+
function buildRegistry(from, to) {
|
|
82
|
+
const paths = sourcesIn(from);
|
|
83
|
+
const owner = /* @__PURE__ */ new Map();
|
|
84
|
+
for (const path of paths) owner.set(path, ownerOf(path));
|
|
85
|
+
const grouped = /* @__PURE__ */ new Map();
|
|
86
|
+
for (const path of paths) {
|
|
87
|
+
const name = owner.get(path);
|
|
88
|
+
grouped.set(name, [...grouped.get(name) ?? [], path]);
|
|
89
|
+
}
|
|
90
|
+
const items = [...grouped].map(([name, own]) => {
|
|
91
|
+
const dependencies = /* @__PURE__ */ new Set();
|
|
92
|
+
const registryDependencies = /* @__PURE__ */ new Set();
|
|
93
|
+
const files = own.map((path) => {
|
|
94
|
+
const content = readFileSync(join(from, path), "utf8");
|
|
95
|
+
for (const specifier of specifiersIn(content)) {
|
|
96
|
+
if (!specifier.startsWith(".")) {
|
|
97
|
+
dependencies.add(packageOf(specifier));
|
|
98
|
+
continue;
|
|
99
|
+
}
|
|
100
|
+
const resolved = relative(from, resolve(join(from, dirname(path)), specifier)).replaceAll("\\", "/");
|
|
101
|
+
const found = owner.get(resolved);
|
|
102
|
+
if (found !== void 0 && found !== name) registryDependencies.add(found);
|
|
103
|
+
}
|
|
104
|
+
return {
|
|
105
|
+
path,
|
|
106
|
+
type: typeOf(path),
|
|
107
|
+
content
|
|
108
|
+
};
|
|
109
|
+
});
|
|
110
|
+
return {
|
|
111
|
+
name,
|
|
112
|
+
type: typeOf(own[0]),
|
|
113
|
+
title: titleOf(name),
|
|
114
|
+
dependencies: [...dependencies].toSorted(),
|
|
115
|
+
devDependencies: [],
|
|
116
|
+
registryDependencies: [...registryDependencies].toSorted(),
|
|
117
|
+
files,
|
|
118
|
+
categories: []
|
|
119
|
+
};
|
|
120
|
+
});
|
|
121
|
+
mkdirSync(to, { recursive: true });
|
|
122
|
+
for (const item of items) writeFileSync(join(to, `${item.name}.json`), `${JSON.stringify(item, null, 2)}\n`);
|
|
123
|
+
writeFileSync(join(to, "index.json"), `${JSON.stringify({
|
|
124
|
+
name: "registry",
|
|
125
|
+
items: items.map((item) => ({
|
|
126
|
+
name: item.name,
|
|
127
|
+
type: item.type,
|
|
128
|
+
title: item.title,
|
|
129
|
+
dependencies: item.dependencies,
|
|
130
|
+
registryDependencies: item.registryDependencies,
|
|
131
|
+
files: item.files.map((file) => file.path)
|
|
132
|
+
}))
|
|
133
|
+
}, null, 2)}\n`);
|
|
134
|
+
return items.length;
|
|
135
|
+
}
|
|
136
|
+
export { buildRegistry };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Exported so the suite can drive the commands, and guarded so importing it
|
|
3
|
+
* does not run one. The guard compares the script node was asked to run with
|
|
4
|
+
* this module rather than reading `import.meta.main`, which node only defines
|
|
5
|
+
* from 24.2 and so is `undefined` for the built `bin` on every older node the
|
|
6
|
+
* engines range admits. `argv[1]` is the `.bin` symlink under a package
|
|
7
|
+
* manager, hence the realpath.
|
|
8
|
+
*/
|
|
9
|
+
export declare function run(): Promise<void>;
|