@galaxy-stack/blackhole-cli 2.0.12 → 2.0.14

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.
@@ -1,7 +1,12 @@
1
1
  ---
2
2
  name: galaxy-ui
3
- version: 0.2.0
4
3
  description: Guide for building UIs with Galaxy UI components across React, Vue, Angular, React Native, and Flutter. Use when the user asks to create UIs, add components, scaffold projects with the Nebula CLI, style with Tailwind v3/v4, or asks about Galaxy component APIs and patterns. Requires using the Nebula CLI for installation and referencing real component APIs (via MCP tools or docs) before writing code.
4
+ version: 1.1.0
5
+ # The companion MCP is installed separately and answers the props lookups this skill routes to;
6
+ # get_component { id, section } with real per-component props arrives with nebula-mcp 1.1.0, and
7
+ # older servers answer an empty manifest for a component that exists.
8
+ requires:
9
+ nebula: ">=1.1.0"
5
10
  ---
6
11
 
7
12
  # Galaxy UI
@@ -10,21 +15,42 @@ Galaxy UI is a multi-framework component library (73 React components, 69 Vue/An
10
15
 
11
16
  Package registry: npm scope `@galaxy-stack`. CLI: `@galaxy-stack/nebula-cli` (command: `nebula`).
12
17
 
13
- ## Ground truth rule
18
+ This file is the rulebook. Component APIs are **data**, and the companion MCP server
19
+ (`@galaxy-stack/nebula-mcp`) serves them from the canonical manifests — never guess props from
20
+ shadcn/ui or another library, and never copy a component's source by hand.
14
21
 
15
- **Before writing any component code**, verify the real API:
22
+ ## Ground truth
16
23
 
17
- - Use the MCP tools (`get_component`, `get_component_source`) if the `nebula-mcp` server is connected
18
- - Otherwise check https://galaxy-nebula.vercel.app/components/<name>
24
+ | Need | Call |
25
+ |---|---|
26
+ | Find a component by intent ("pricing table", "stat card", "searchable select") | `search_components { query }` |
27
+ | Every component with its per-framework status | `list_components { framework? }` |
28
+ | One component's manifest | `get_component { id, section? }` — `section` is `summary` (default), `props`, `files` or `raw`; prefer a section to stay inside the token budget |
29
+ | The real source of one file | `get_component_source { id, framework }` — omit `file` to list the files that are actually bundled, then read one |
30
+ | What exists per framework | `get_coverage` |
19
31
 
20
- Never guess props from shadcn/ui or other libraries — Galaxy has its own contracts (documented per component in the docs pages).
32
+ If `nebula-mcp` is not connected, the docs site is the fallback:
33
+ `https://galaxy-nebula.vercel.app/components/<name>` (and `/assistant/overview` for the
34
+ `assistant-*` set). Do not infer an API from a screenshot or from another design system.
21
35
 
22
36
  ## Workflow
23
37
 
24
- 1. **Detect the user's framework** (React, Vue, Angular, Next.js, Nuxt.js, React Native, Flutter)
25
- 2. **Check setup**: run `nebula doctor` (or ask if `components.json` exists)
26
- 3. **Add components**: `npx @galaxy-stack/nebula-cli@latest add <names>` — supports multiple names, `--all`, `--overwrite` (backs up to `.galaxy/backups/`), `--registry-url <url>` for versioned CDN. Always use the CLI; never copy component source from MCP tools or docs by hand, because `add` also wires dependencies, path aliases, and Tailwind/CSS-var tokens.
27
- 4. **Verify**: `nebula doctor` reports alias, dependency, and Tailwind issues
38
+ 1. **Detect the user's framework** (React, Vue, Angular, Next.js, Nuxt.js, React Native, Flutter).
39
+ 2. **Check setup**: run `nebula doctor` (or ask whether `components.json` exists).
40
+ 3. **Add components**: `nebula add <names>` — supports multiple names, `--all`,
41
+ `--overwrite` (backs up to `.galaxy/backups/`), `--registry-url <url>` for a
42
+ versioned CDN. Always install through the CLI: it also wires dependencies, path aliases and the
43
+ Tailwind/CSS-var tokens, which copying source by hand does not.
44
+ 4. **Verify**: `nebula doctor` reports alias, dependency and Tailwind problems.
45
+
46
+ ### Use the installed binaries, never `bunx …@latest`
47
+
48
+ `orbit` (from `@galaxy-stack/orbit-cli`) and `nebula` are already on `PATH` (otherwise
49
+ `~/.bun/bin/orbit`). Run them directly — `orbit new gymflow-backend --directory backend`,
50
+ `nebula init --yes --theme violet`, `nebula add button card badge`. `bunx`
51
+ re-resolves the package from the registry on every call and stalls for minutes when the registry is
52
+ slow (measured: 180s, then 300s, then 480s inside one step). If a binary really is missing, prefer
53
+ `bunx --offline` or a pinned version with a generous timeout.
28
54
 
29
55
  ## Component selection quick guide
30
56
 
@@ -35,9 +61,11 @@ Never guess props from shadcn/ui or other libraries — Galaxy has its own contr
35
61
  - Dates: `calendar`, `calendar-range`, `date-picker`, `date-range-picker`, `date-time-picker`, `time-picker`
36
62
  - Layout: `card`, `separator`, `tabs`, `accordion`, `collapsible`, `resizable`, `scroll-area`, `aspect-ratio`, `toolbar`
37
63
  - Blocks (composite pages): `login-block`, `pricing-block`, `dashboard-block`, `sidebar`, `chat-ui`, `authentication`, `email`, `featured`
38
- - Assistant UI (React phase 1, for editor webviews/panels): `chat-panel`, `agent-activity`, `diff-review`, `prompt-box` — see https://galaxy-nebula.vercel.app/assistant/overview
64
+ - Assistant UI (React phase 1, for editor webviews/panels): `chat-panel`, `agent-activity`, `diff-review`, `prompt-box`
39
65
 
40
- Web-only components (not on mobile): `breadcrumb`, `command`, `combobox`, `dashboard-block`, `data-table`, `kbd`, `toolbar`, `resizable`, `scroll-area` — plus all four `assistant-*` components.
66
+ Web-only components (not on mobile): `breadcrumb`, `command`, `combobox`, `dashboard-block`,
67
+ `data-table`, `kbd`, `toolbar`, `resizable`, `scroll-area` — plus all four
68
+ `assistant-*` components. `get_coverage` is the authority when a list here is not enough.
41
69
 
42
70
  ## Critical framework notes
43
71
 
@@ -48,41 +76,21 @@ Read `references/framework-notes.md` for per-framework gotchas before writing co
48
76
  - **React Native**: NativeWind classes, no web date libraries
49
77
  - **Flutter**: Material 3 widgets, `Galaxy` prefix
50
78
 
51
- ### Scaffolding: use the installed binaries, never `bunx …@latest`
52
-
53
- `orbit` (from `@galaxy-stack/orbit-cli`) and `nebula` (from `@galaxy-stack/nebula-cli`) are
54
- installed in this environment — on `PATH`, otherwise at `~/.bun/bin/orbit`. Run them
55
- directly:
56
-
57
- ```sh
58
- orbit new gymflow-backend --directory backend
59
- nebula init --yes --theme violet
60
- nebula add button card badge
61
- ```
79
+ ## Styling
62
80
 
63
- Do **not** run `bunx @galaxy-stack/orbit-cli@latest …`: bunx re-resolves the package from the
64
- registry on every call, and when the registry is slow it stalls on "Resolving dependencies"
65
- for minutes (measured: 180s, then 300s, then 480s inside a single step, which burned most of
66
- that step's budget). If a binary is really missing, prefer `bunx --offline` (the local cache)
67
- or a pinned version (`bunx @galaxy-stack/orbit-cli@0.1.13`) with a generous timeout.
81
+ All components use Tailwind + CSS variables (design tokens). Read `references/tailwind.md` for the
82
+ v3/v4 setup. Theme presets: `nebula init --theme violet|green|blue|default`.
68
83
 
69
84
  ## Verification
70
85
 
71
86
  Prove a UI change with bounded tools, not with a running server:
72
87
 
73
- - `validate_project` with `checks: ["build"]` (the Vite build) plus `lint`/`typecheck`
74
- for the packages you touched, and `nebula doctor` for alias, dependency and token
75
- wiring.
76
- - Do **not** start `vite`/`npm run dev` as a check. A dev server never exits, produces
77
- no completion evidence, and the log or probe file written for it is an unreviewed
78
- write that invalidates the validation it was meant to support. Start a server only
79
- when the task explicitly asks to exercise the running app, through the bounded
80
- session capability, and stop it before the final validation.
81
-
82
- ## Styling
83
-
84
- All components use Tailwind + CSS variables (design tokens). Read `references/tailwind.md` for v3/v4 setup. Theme presets: `nebula init --theme violet|green|blue|default`.
85
-
86
- ## AI data access (MCP)
87
-
88
- If the user has the `nebula-mcp` server connected, prefer its tools for live data over this skill's references — they are generated from canonical manifests and always current.
88
+ - `validate_project` with `checks: ["build"]` plus `lint`/`typecheck` for the packages you
89
+ touched, and `nebula doctor` for alias, dependency and token wiring.
90
+ - Do **not** start `vite`/`npm run dev` as a check: a dev server never exits, produces no
91
+ completion evidence, and any log or probe file it writes is an unreviewed write that invalidates
92
+ the validation it was meant to support. Start a server only when the task explicitly asks to
93
+ exercise the running app — with `run_command`, not by searching for a session tool (this catalog
94
+ has no `manage_session`/preview capability): start it detached, probe the URL with `curl -sf`,
95
+ and stop it before the final validation.
96
+ - Props you used must exist in the component's manifest (`get_component { id, section: "props" }`).