@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 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
- # Temporary Holding Version
1
+ # @barqjs/ui-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 };
@@ -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>;