@galaxy-stack/blackhole-cli 2.0.0-alpha.10

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.
Files changed (104) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +133 -0
  3. package/dist/application.d.ts +63 -0
  4. package/dist/application.d.ts.map +1 -0
  5. package/dist/application.js +272 -0
  6. package/dist/application.js.map +1 -0
  7. package/dist/cli-meta.d.ts +15 -0
  8. package/dist/cli-meta.d.ts.map +1 -0
  9. package/dist/cli-meta.js +37 -0
  10. package/dist/cli-meta.js.map +1 -0
  11. package/dist/cli.d.ts +3 -0
  12. package/dist/cli.d.ts.map +1 -0
  13. package/dist/cli.js +177 -0
  14. package/dist/cli.js.map +1 -0
  15. package/dist/composer.d.ts +13 -0
  16. package/dist/composer.d.ts.map +1 -0
  17. package/dist/composer.js +115 -0
  18. package/dist/composer.js.map +1 -0
  19. package/dist/flow.d.ts +44 -0
  20. package/dist/flow.d.ts.map +1 -0
  21. package/dist/flow.js +102 -0
  22. package/dist/flow.js.map +1 -0
  23. package/dist/logs.d.ts +25 -0
  24. package/dist/logs.d.ts.map +1 -0
  25. package/dist/logs.js +80 -0
  26. package/dist/logs.js.map +1 -0
  27. package/dist/memory-import.d.ts +28 -0
  28. package/dist/memory-import.d.ts.map +1 -0
  29. package/dist/memory-import.js +51 -0
  30. package/dist/memory-import.js.map +1 -0
  31. package/dist/options.d.ts +32 -0
  32. package/dist/options.d.ts.map +1 -0
  33. package/dist/options.js +121 -0
  34. package/dist/options.js.map +1 -0
  35. package/dist/sessions.d.ts +16 -0
  36. package/dist/sessions.d.ts.map +1 -0
  37. package/dist/sessions.js +56 -0
  38. package/dist/sessions.js.map +1 -0
  39. package/dist/spill.d.ts +30 -0
  40. package/dist/spill.d.ts.map +1 -0
  41. package/dist/spill.js +44 -0
  42. package/dist/spill.js.map +1 -0
  43. package/dist/terminal-input.d.ts +10 -0
  44. package/dist/terminal-input.d.ts.map +1 -0
  45. package/dist/terminal-input.js +10 -0
  46. package/dist/terminal-input.js.map +1 -0
  47. package/dist/timeline.d.ts +31 -0
  48. package/dist/timeline.d.ts.map +1 -0
  49. package/dist/timeline.js +280 -0
  50. package/dist/timeline.js.map +1 -0
  51. package/dist/tui.d.ts +11 -0
  52. package/dist/tui.d.ts.map +1 -0
  53. package/dist/tui.js +269 -0
  54. package/dist/tui.js.map +1 -0
  55. package/dist/web/command.d.ts +3 -0
  56. package/dist/web/command.d.ts.map +1 -0
  57. package/dist/web/command.js +37 -0
  58. package/dist/web/command.js.map +1 -0
  59. package/dist/web/credentials.d.ts +17 -0
  60. package/dist/web/credentials.d.ts.map +1 -0
  61. package/dist/web/credentials.js +36 -0
  62. package/dist/web/credentials.js.map +1 -0
  63. package/dist/web/doctor.d.ts +4 -0
  64. package/dist/web/doctor.d.ts.map +1 -0
  65. package/dist/web/doctor.js +79 -0
  66. package/dist/web/doctor.js.map +1 -0
  67. package/dist/web/dsh.d.ts +11 -0
  68. package/dist/web/dsh.d.ts.map +1 -0
  69. package/dist/web/dsh.js +59 -0
  70. package/dist/web/dsh.js.map +1 -0
  71. package/dist/web/open-browser.d.ts +3 -0
  72. package/dist/web/open-browser.d.ts.map +1 -0
  73. package/dist/web/open-browser.js +19 -0
  74. package/dist/web/open-browser.js.map +1 -0
  75. package/dist/web/options.d.ts +23 -0
  76. package/dist/web/options.d.ts.map +1 -0
  77. package/dist/web/options.js +154 -0
  78. package/dist/web/options.js.map +1 -0
  79. package/dist/web/paths.d.ts +17 -0
  80. package/dist/web/paths.d.ts.map +1 -0
  81. package/dist/web/paths.js +39 -0
  82. package/dist/web/paths.js.map +1 -0
  83. package/dist/web/web.d.ts +17 -0
  84. package/dist/web/web.d.ts.map +1 -0
  85. package/dist/web/web.js +153 -0
  86. package/dist/web/web.js.map +1 -0
  87. package/package.json +65 -0
  88. package/skills/galaxy-ui/SKILL.md +56 -0
  89. package/skills/galaxy-ui/references/cli-workflows.md +54 -0
  90. package/skills/galaxy-ui/references/component-patterns.md +46 -0
  91. package/skills/galaxy-ui/references/framework-notes.md +35 -0
  92. package/skills/galaxy-ui/references/tailwind.md +23 -0
  93. package/skills/orbit-framework/SKILL.md +126 -0
  94. package/web/brand/client.template.js +217 -0
  95. package/web/brand/favicon.png +0 -0
  96. package/web/brand/lib/client.js +1205 -0
  97. package/web/brand/lib/favicon.js +1 -0
  98. package/web/brand/lib/index.js +143 -0
  99. package/web/brand/logo.png +0 -0
  100. package/web/brand/package.json +35 -0
  101. package/web/brand/vi.locales.json +989 -0
  102. package/web/patches/gbh-brand.patch.yml +13 -0
  103. package/web/patches/gbh-ui.patch.yml +18 -0
  104. package/web/patches/gbh-web.patch.yml +68 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/web/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,wFAAwF;AACxF,MAAM,UAAU,WAAW;IACzB,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,MAAM;IACpB,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,mBAAmB,CAAC,CAAC;AACxD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;AACvD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC;AAC1D,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW;IACzB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;IACrC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IAC9E,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;AAC7C,CAAC"}
@@ -0,0 +1,17 @@
1
+ import type { WebOptions } from "./options.js";
2
+ export interface WebPlan {
3
+ command: string;
4
+ args: string[];
5
+ env: NodeJS.ProcessEnv;
6
+ patches: string[];
7
+ home: string;
8
+ runtimeSource: string;
9
+ keySource?: string;
10
+ }
11
+ /** Link the gbh brand client package into the profile node_modules (best effort). */
12
+ export declare function ensureBrandLink(home: string): string;
13
+ /** Resolve the DSH command, patch list, and environment for gbh web. */
14
+ export declare function planWeb(options: WebOptions): WebPlan;
15
+ /** Boot the DSH web GUI, open the browser, and propagate the exit code. */
16
+ export declare function runWeb(options: WebOptions): Promise<number>;
17
+ //# sourceMappingURL=web.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/web/web.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+BD,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiBpD;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAyBpD;AAED,2EAA2E;AAC3E,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDjE"}
@@ -0,0 +1,153 @@
1
+ import { spawn } from "node:child_process";
2
+ import { existsSync, mkdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
3
+ import { join, resolve } from "node:path";
4
+ import { resolveDsh } from "./dsh.js";
5
+ import { brandPackagePath, brandPatchPath, bundledPatchPath, defaultHome, overlayPath, uiPatchPath } from "./paths.js";
6
+ import { credentialsFilePath, GALAXY_KEY_ENV, resolveGalaxyKeySource } from "./credentials.js";
7
+ import { openUrl } from "./open-browser.js";
8
+ const URL_PATTERN = /dsh web:\s*(\S+)/;
9
+ function yamlScalar(value) {
10
+ return JSON.stringify(value);
11
+ }
12
+ function writeOverlay(options, home) {
13
+ const rows = [];
14
+ if (options.model !== undefined) {
15
+ rows.push("- id: agent-default-model");
16
+ rows.push(" config:");
17
+ rows.push(" provider: galaxy");
18
+ rows.push(" model: " + yamlScalar(options.model));
19
+ }
20
+ if (options.preset !== undefined) {
21
+ rows.push("- id: agent-presets");
22
+ rows.push(" config:");
23
+ rows.push(" default: " + yamlScalar(options.preset));
24
+ }
25
+ if (rows.length === 0)
26
+ return undefined;
27
+ mkdirSync(home, { recursive: true });
28
+ const path = overlayPath(home);
29
+ writeFileSync(path, rows.join("\n") + "\n", "utf8");
30
+ return path;
31
+ }
32
+ function shellQuote(value) {
33
+ if (value.length > 0 && /^[A-Za-z0-9_@%+=:,.-]+$/.test(value))
34
+ return value;
35
+ return "'" + value.split("'").join("'\\''") + "'";
36
+ }
37
+ /** Link the gbh brand client package into the profile node_modules (best effort). */
38
+ export function ensureBrandLink(home) {
39
+ const dir = join(home, "profiles", "node_modules", "@galaxy-stack");
40
+ const link = join(dir, "gbh-brand");
41
+ const target = brandPackagePath();
42
+ try {
43
+ mkdirSync(dir, { recursive: true });
44
+ if (existsSync(link)) {
45
+ let current;
46
+ try {
47
+ current = readlinkSync(link);
48
+ }
49
+ catch {
50
+ current = undefined;
51
+ }
52
+ if (current === target)
53
+ return link;
54
+ rmSync(link, { recursive: true, force: true });
55
+ }
56
+ symlinkSync(target, link, "dir");
57
+ }
58
+ catch {
59
+ return link;
60
+ }
61
+ return link;
62
+ }
63
+ /** Resolve the DSH command, patch list, and environment for gbh web. */
64
+ export function planWeb(options) {
65
+ const runtime = resolveDsh();
66
+ const home = options.home !== undefined ? options.home : defaultHome();
67
+ const patches = [bundledPatchPath(), uiPatchPath()];
68
+ if (options.brand) {
69
+ ensureBrandLink(home);
70
+ patches.push(brandPatchPath());
71
+ }
72
+ const overlay = writeOverlay(options, home);
73
+ if (overlay !== undefined)
74
+ patches.push(overlay);
75
+ for (const extra of options.patches)
76
+ patches.push(resolve(extra));
77
+ const args = [...runtime.baseArgs, "--profile", options.profile];
78
+ for (const patch of patches)
79
+ args.push("--patch", patch);
80
+ args.push("--no-open", "--port", String(options.port), "--host", options.host);
81
+ const env = { ...process.env, DSH_HOME: home, DSH_TOOLS_MODE: options.toolsMode };
82
+ const keySource = resolveGalaxyKeySource(home, env);
83
+ return {
84
+ command: runtime.command,
85
+ args,
86
+ env,
87
+ patches,
88
+ home,
89
+ runtimeSource: runtime.source,
90
+ ...(keySource === undefined ? {} : { keySource }),
91
+ };
92
+ }
93
+ /** Boot the DSH web GUI, open the browser, and propagate the exit code. */
94
+ export async function runWeb(options) {
95
+ const plan = planWeb(options);
96
+ if (options.dryRun) {
97
+ process.stdout.write("cwd: " + process.cwd() + "\n");
98
+ process.stdout.write("DSH_HOME=" + plan.home + " DSH_TOOLS_MODE=" + options.toolsMode + "\n");
99
+ process.stdout.write("runtime: " + plan.runtimeSource + "\n");
100
+ process.stdout.write("galaxy key: " + (plan.keySource === undefined ? "NOT SET" : "set via " + plan.keySource) + "\n");
101
+ process.stdout.write("patches:\n");
102
+ for (const patch of plan.patches)
103
+ process.stdout.write(" " + patch + "\n");
104
+ process.stdout.write(shellQuote(plan.command) + " " + plan.args.map(shellQuote).join(" ") + "\n");
105
+ return 0;
106
+ }
107
+ if (plan.keySource === undefined) {
108
+ process.stderr.write("gbh: No Galaxy API key yet: " + GALAXY_KEY_ENV + " is not exported and " + credentialsFilePath(plan.home) + " does not reference it. " +
109
+ "The Galaxy Blackhole dialog will ask for it on first load and store it there.\n");
110
+ }
111
+ const child = spawn(plan.command, plan.args, { cwd: process.cwd(), env: plan.env, stdio: ["inherit", "pipe", "pipe"] });
112
+ let seen = "";
113
+ let opened = false;
114
+ const scan = (chunk) => {
115
+ if (opened || !options.open)
116
+ return;
117
+ seen += chunk;
118
+ const match = seen.match(URL_PATTERN);
119
+ if (match !== null && match[1] !== undefined) {
120
+ opened = true;
121
+ openUrl(match[1]);
122
+ }
123
+ };
124
+ child.stdout?.setEncoding("utf8");
125
+ child.stdout?.on("data", (chunk) => {
126
+ process.stdout.write(chunk);
127
+ scan(chunk);
128
+ });
129
+ child.stderr?.setEncoding("utf8");
130
+ child.stderr?.on("data", (chunk) => {
131
+ process.stderr.write(chunk);
132
+ });
133
+ const onSigterm = () => {
134
+ if (!child.killed)
135
+ child.kill("SIGTERM");
136
+ };
137
+ process.on("SIGTERM", onSigterm);
138
+ const code = await new Promise((resolvePromise) => {
139
+ child.on("error", (error) => {
140
+ process.stderr.write("gbh: failed to start DSH: " + error.message + "\n");
141
+ resolvePromise(1);
142
+ });
143
+ child.on("close", (exitCode, signal) => {
144
+ if (exitCode !== null)
145
+ resolvePromise(exitCode);
146
+ else
147
+ resolvePromise(signal === "SIGINT" ? 130 : 1);
148
+ });
149
+ });
150
+ process.off("SIGTERM", onSigterm);
151
+ return code;
152
+ }
153
+ //# sourceMappingURL=web.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"web.js","sourceRoot":"","sources":["../../src/web/web.ts"],"names":[],"mappings":"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"}
package/package.json ADDED
@@ -0,0 +1,65 @@
1
+ {
2
+ "name": "@galaxy-stack/blackhole-cli",
3
+ "version": "2.0.0-alpha.10",
4
+ "private": false,
5
+ "description": "Galaxy Code CLI and terminal UI for the Galaxy agent runtime",
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "bin": {
9
+ "blackhole": "dist/cli.js"
10
+ },
11
+ "files": [
12
+ "dist",
13
+ "README.md",
14
+ "LICENSE",
15
+ "skills",
16
+ "web"
17
+ ],
18
+ "scripts": {
19
+ "build": "node scripts/build.mjs",
20
+ "core:build": "npm --prefix ../galaxy-ai-coder-core run build",
21
+ "dev": "tsx src/cli.ts",
22
+ "start": "node dist/cli.js",
23
+ "typecheck": "tsc --noEmit -p tsconfig.json",
24
+ "test": "tsx --test test/*.test.ts test/*.test.tsx",
25
+ "check": "npm run core:build && npm run typecheck && npm test && npm run build",
26
+ "publish:alpha": "node scripts/publish.mjs",
27
+ "publish:release": "node scripts/publish.mjs"
28
+ },
29
+ "dependencies": {
30
+ "@assistant-ui/react-ink": "^0.0.44",
31
+ "@galaxy-stack/ai-coder-core": "0.3.0-alpha.18",
32
+ "@modelcontextprotocol/sdk": "^1.30.1",
33
+ "ink": "7.1.1",
34
+ "react": "^19.3.0",
35
+ "string-width": "^8.2.2",
36
+ "wrap-ansi": "^9.0.2"
37
+ },
38
+ "devDependencies": {
39
+ "@types/node": "^22.19.15",
40
+ "@types/react": "^19.3.0",
41
+ "ink-testing-library": "^4.0.0",
42
+ "tsx": "^4.21.0",
43
+ "typescript": "~5.9.2"
44
+ },
45
+ "engines": {
46
+ "node": ">=22.13"
47
+ },
48
+ "packageManager": "npm@10",
49
+ "repository": {
50
+ "type": "git",
51
+ "url": "https://github.com/galaxy-blackhole/galaxy-code.git"
52
+ },
53
+ "bugs": {
54
+ "url": "https://github.com/galaxy-blackhole/galaxy-code/issues"
55
+ },
56
+ "homepage": "https://github.com/galaxy-blackhole/galaxy-code#readme",
57
+ "keywords": [
58
+ "galaxy-blackhole",
59
+ "blackhole",
60
+ "ai-coder",
61
+ "ai",
62
+ "cli",
63
+ "coding-agent"
64
+ ]
65
+ }
@@ -0,0 +1,56 @@
1
+ ---
2
+ name: galaxy-ui
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
+ ---
5
+
6
+ # Galaxy UI
7
+
8
+ Galaxy UI is a multi-framework component library (73 React components, 69 Vue/Angular, 67 mobile per framework) built on the shadcn philosophy: components are copied into the user's project and remain fully editable.
9
+
10
+ Package registry: npm scope `@galaxy-stack`. CLI: `@galaxy-stack/nebula-cli` (command: `nebula`).
11
+
12
+ ## Ground truth rule
13
+
14
+ **Before writing any component code**, verify the real API:
15
+
16
+ - Use the MCP tools (`get_component`, `get_component_source`) if the `nebula-mcp` server is connected
17
+ - Otherwise check https://galaxy-nebula.vercel.app/components/<name>
18
+
19
+ Never guess props from shadcn/ui or other libraries — Galaxy has its own contracts (documented per component in the docs pages).
20
+
21
+ ## Workflow
22
+
23
+ 1. **Detect the user's framework** (React, Vue, Angular, Next.js, Nuxt.js, React Native, Flutter)
24
+ 2. **Check setup**: run `nebula doctor` (or ask if `components.json` exists)
25
+ 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.
26
+ 4. **Verify**: `nebula doctor` reports alias, dependency, and Tailwind issues
27
+
28
+ ## Component selection quick guide
29
+
30
+ - Forms: `input`, `textarea`, `select`, `checkbox`, `radio-group`, `switch`, `slider`, `form`, `tags-input`, `otp-input`, `combobox` (searchable select)
31
+ - Overlays: `dialog`, `alert-dialog`, `sheet`, `popover`, `tooltip`, `dropdown-menu`, `command`
32
+ - Data: `table`, `data-table` (React/Vue only), `pagination`, `tabs`, `accordion`, `card`
33
+ - Feedback: `alert`, `toast`, `progress`, `spinner`, `skeleton`, `badge`
34
+ - Dates: `calendar`, `calendar-range`, `date-picker`, `date-range-picker`, `date-time-picker`, `time-picker`
35
+ - Layout: `card`, `separator`, `tabs`, `accordion`, `collapsible`, `resizable`, `scroll-area`, `aspect-ratio`, `toolbar`
36
+ - Blocks (composite pages): `login-block`, `pricing-block`, `dashboard-block`, `sidebar`, `chat-ui`, `authentication`, `email`, `featured`
37
+ - 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
38
+
39
+ Web-only components (not on mobile): `breadcrumb`, `command`, `combobox`, `dashboard-block`, `data-table`, `kbd`, `toolbar`, `resizable`, `scroll-area` — plus all four `assistant-*` components.
40
+
41
+ ## Critical framework notes
42
+
43
+ Read `references/framework-notes.md` for per-framework gotchas before writing code:
44
+
45
+ - **Vue**: date components use radix `DateValue` (not native `Date`)
46
+ - **Angular**: standalone components, `ui-*` selectors, `ControlValueAccessor` for form controls
47
+ - **React Native**: NativeWind classes, no web date libraries
48
+ - **Flutter**: Material 3 widgets, `Galaxy` prefix
49
+
50
+ ## Styling
51
+
52
+ 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`.
53
+
54
+ ## AI data access (MCP)
55
+
56
+ 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.
@@ -0,0 +1,54 @@
1
+ # Nebula CLI Workflows
2
+
3
+ Command: `npx @galaxy-stack/nebula-cli@latest <cmd>` or install globally: `npm install -g @galaxy-stack/nebula-cli` then `nebula <cmd>`.
4
+
5
+ ## init
6
+
7
+ ```bash
8
+ npx @galaxy-stack/nebula-cli@latest init [--theme violet|green|blue|default] [-y] [--cwd ./app]
9
+ ```
10
+
11
+ Creates `components.json`, scaffolds Tailwind (v4-first, preserves v3), configures aliases, installs dependencies.
12
+
13
+ ## add
14
+
15
+ ```bash
16
+ npx @galaxy-stack/nebula-cli@latest add button input dialog
17
+ npx @galaxy-stack/nebula-cli@latest add --all
18
+ npx @galaxy-stack/nebula-cli@latest add data-table --overwrite # backup to .galaxy/backups/
19
+ npx @galaxy-stack/nebula-cli@latest add toast --registry-url https://galaxy-nebula.vercel.app/registry/<version>
20
+ ```
21
+
22
+ - Auto-installs dependencies (date-fns, vue-sonner, radix packages...)
23
+ - `--overwrite` backs up existing files first
24
+ - `--registry-url` fetches from a versioned, sha256-verified CDN
25
+
26
+ ## list
27
+
28
+ ```bash
29
+ nebula list [--framework react] [--category form]
30
+ ```
31
+
32
+ ## doctor
33
+
34
+ ```bash
35
+ nebula doctor
36
+ ```
37
+
38
+ Validates `components.json`, aliases, Tailwind setup, dependencies. Run after any manual config change.
39
+
40
+ ## diff / update
41
+
42
+ ```bash
43
+ nebula diff <component> # local vs registry (unchanged/modified/missing)
44
+ nebula update <component> # re-download (backs up local changes)
45
+ ```
46
+
47
+ ## migrate tailwind
48
+
49
+ ```bash
50
+ nebula migrate tailwind --dry-run # preview
51
+ nebula migrate tailwind --yes # apply
52
+ ```
53
+
54
+ Converts v3 → v4: PostCSS config, CSS-first stylesheet, dependency swap.
@@ -0,0 +1,46 @@
1
+ # Component Patterns
2
+
3
+ ## Form composition (web)
4
+
5
+ ```vue
6
+ <Form class="space-y-4" @submit.prevent>
7
+ <FormItem>
8
+ <FormLabel for="email">Email</FormLabel>
9
+ <Input id="email" type="email" placeholder="m@example.com" />
10
+ <FormDescription>We'll never share your email.</FormDescription>
11
+ <FormMessage />
12
+ </FormItem>
13
+ <Button type="submit">Submit</Button>
14
+ </Form>
15
+ ```
16
+
17
+ ## Dialog flow
18
+
19
+ Dialog/AlertDialog use radix state: render `<DialogTrigger as-child>` with a Button, content hidden until open. Never pre-open dialogs in previews.
20
+
21
+ ## Date pickers
22
+
23
+ DatePicker = Popover (trigger button showing formatted date) + Calendar in PopoverContent. In Vue, pass/emit radix `DateValue`; format with date-fns after converting to native Date.
24
+
25
+ ## Data Table
26
+
27
+ `<DataTable :columns="[...]" :data="[...]" />` — columns define key/header/sortable. Sorting toggles asc/desc on header click.
28
+
29
+ ## Toast
30
+
31
+ Mount `<Toaster />` once (App root), fire with `toast('message')` imported from the toast component index.
32
+
33
+ ## Blocks
34
+
35
+ Login/pricing/dashboard blocks are composite pages — install with `nebula add login-block` and customize. Dashboard block = sidebar + stat cards + table.
36
+
37
+ ## Assistant UI (React, phase 1)
38
+
39
+ Assistant components power AI-native surfaces (VSCode webviews, sidebars, agent panels). All four live in `@/components/assistant/<name>/` and are stateless/dumb — state lives in the host app:
40
+
41
+ - `ChatPanel` — message list + tool-call cards + composer. Props: `messages`, `model`, `onSendMessage`, `onStop`, `busy` via `messages.some(m => m.streaming)`.
42
+ - `AgentActivity` — task checklist + progress + tool log. Props: `tasks` (`pending|running|completed|error`), `toolEvents`, `status`, `elapsedLabel`.
43
+ - `DiffReview` — accept/reject per file, unified diff lines with `+`/`-` prefixes. Props: `files` (`DiffFile[]`), `onAccept`, `onReject`, `onAcceptAll`, `onRejectAll`.
44
+ - `PromptBox` — standalone composer with auto-resize, slash commands, attachments, model pill.
45
+
46
+ Install with `nebula add chat-panel` etc. Docs: https://galaxy-nebula.vercel.app/assistant/overview
@@ -0,0 +1,35 @@
1
+ # Framework Notes — gotchas per framework
2
+
3
+ ## Vue
4
+
5
+ - **Date components** (`date-picker`, `date-range-picker`, `calendar`): `modelValue` is radix **`DateValue`** (from `@internationalized/date`), NOT native `Date`. Bridge with `.toDate(getLocalTimeZone())`.
6
+ - **Calendar** uses radix-vue subcomponents (`CalendarRoot`, `CalendarGrid`...). The slot provides `grid` = array of `{ value, rows, cells }` objects — iterate `month.rows`, pass `:date` to `CalendarCell`, `:day` + `:month` to `CalendarCellTrigger`.
7
+ - **Toast** uses `vue-sonner` (`Toaster` + `toast()` from the toast component index).
8
+ - Templates cannot use TS assertions directly in expressions — move to script or computed.
9
+
10
+ ## Angular
11
+
12
+ - All components are **standalone** with `ui-*` selectors (e.g., `ui-combobox`, `ui-data-table`).
13
+ - Form controls implement `ControlValueAccessor` — use `[(ngModel)]` or ReactiveForms.
14
+ - **Alert Dialog** uses `@radix-ng/primitives` with an injected service (`RdxAlertDialogService`), not template-only wiring.
15
+ - Blocks live in `blocks/<name>-block/` with their own `index.ts` exports.
16
+
17
+ ## React / Next.js
18
+
19
+ - Reference implementation — all components mirror the shadcn structure with Galaxy contracts.
20
+ - `data-table` uses TanStack-style column definitions.
21
+
22
+ ## React Native
23
+
24
+ - **NativeWind** classes (same Tailwind syntax, `className` prop).
25
+ - No web date libraries — Calendar/TimePicker are custom implementations.
26
+ - Blocks are available (login-block, pricing-block); dashboard-block is web-only.
27
+
28
+ ## Flutter
29
+
30
+ - Material 3 widgets, `Galaxy` prefix (`GalaxyCalendar`, `GalaxyOTPInput`).
31
+ - Date/time pickers delegate to Flutter's native `showDatePicker`/`showTimePicker`.
32
+
33
+ ## Web-only components (not on mobile)
34
+
35
+ `breadcrumb`, `command`, `combobox`, `dashboard-block`, `data-table`, `kbd`, `toolbar`, `resizable`, `scroll-area` — use platform-native equivalents.
@@ -0,0 +1,23 @@
1
+ # Tailwind v3 vs v4
2
+
3
+ Galaxy supports both. `nebula init` auto-detects; `nebula doctor` verifies.
4
+
5
+ ## v4 (default)
6
+
7
+ - PostCSS: single plugin `@tailwindcss/postcss`
8
+ - Stylesheet: `@import "tailwindcss"; @import "tw-animate-css";` + `@custom-variant dark` + `@theme inline` token bridge
9
+ - Deps: `tailwindcss@4`, `tw-animate-css`, `tailwind-merge@3`
10
+ - Dark mode: `@custom-variant dark (&:is(.dark *));`
11
+
12
+ ## v3
13
+
14
+ - `tailwind.config.js` with content globs, `darkMode: ['class']`
15
+ - Deps: `tailwindcss@3.4`, `tailwindcss-animate`, `autoprefixer`, `tailwind-merge@2`
16
+
17
+ ## Design tokens
18
+
19
+ CSS variables (`--background`, `--primary`...) under `:root` and `.dark` are identical between v3/v4 — components map them via semantic utilities. Theme presets change only the variable values.
20
+
21
+ ## Migration
22
+
23
+ `nebula migrate tailwind --dry-run` then `--yes`. Never round-trip v4 → v3.
@@ -0,0 +1,126 @@
1
+ ---
2
+ name: orbit-framework
3
+ description: >
4
+ Guidance for building backend applications with the Orbit framework
5
+ (@galaxy-stack/orbit-*), a NestJS-style framework optimized for the Bun
6
+ runtime. Use when creating modules, controllers, providers, GraphQL APIs,
7
+ microservices, or when migrating from NestJS to Orbit.
8
+ version: 0.1.0
9
+ ---
10
+
11
+ # Orbit Framework Skill
12
+
13
+ Orbit is a NestJS-style backend framework for Bun. Concept mapping from NestJS:
14
+ `@nestjs/common` → `@galaxy-stack/orbit-core`; `class-validator` DTOs → Zod +
15
+ `orbit-validation`; `@nestjs/graphql` → `orbit-graphql`; `@nestjs/microservices`
16
+ → `orbit-microservices` + transport packages; `@nestjs/swagger` → `orbit-swagger`.
17
+
18
+ ## Project rules
19
+
20
+ 1. Runtime is Bun. Use `bun` instead of `node`/`npm`/`pnpm` for all commands:
21
+ `bun install`, `bun run dev`, `bun test`.
22
+ 2. Entry point: `OrbitFactory.create(AppModule)` then `app.listen(3000)`.
23
+ 3. Every feature is a `@Module({ controllers, providers, exports })` class.
24
+ 4. Providers are `@Injectable()` classes injected via constructor.
25
+ 5. Validate all external input with Zod schemas through ValidationPipe.
26
+ 6. Tests run with `bun test`; e2e tests boot a real HTTP server: `OrbitFactory.create(AppModule, { port: 0 })` → `app.listen(0)` → `fetch(\`http://127.0.0.1:${app.port}/…\`)` — `OrbitApplication` has no public `handle()`.
27
+
28
+ ## Scaffolding and dependency wiring
29
+
30
+ Use the Orbit CLI; do not hand-wire modules or add framework packages manually:
31
+
32
+ - New project: `bunx @galaxy-stack/orbit-cli new <app>` (or the installed `orbit new`) scaffolds the app and installs dependencies.
33
+ - New component: `orbit generate <type> <name>` (aliases `orbit g co|s|mo|gu|pi|in|mi|f|res`) creates the file **and updates `@Module` imports automatically**. `orbit g resource <name>` generates a full CRUD resource.
34
+ - Only add packages when the CLI does not cover the case: `bun add @galaxy-stack/orbit-*`. Never edit `package.json`/lockfiles by hand to add a package, and never copy `orbit` sources out of `node_modules`.
35
+
36
+ The companion MCP server (`@galaxy-stack/orbit-mcp`) is for searching knowledge and reviewing code. Its `orbit_scaffold_*` tools only **return** generated content; they do not write files or update module imports. To apply scaffolding in the workspace, use the CLI (or write the returned files deliberately).
37
+
38
+ ## Security baseline (non-negotiable for production code)
39
+
40
+ - `SecurityModule.forRoot({ helmet: true, csrf: true })` — OWASP headers + CSRF.
41
+ - `ThrottlerModule` for rate limiting on auth and write routes.
42
+ - GraphQL: `introspection: false` in production; `security: { maxDepth: 10,
43
+ maxComplexity: 1000, maxAliases: 30 }`; playground disabled in production.
44
+ - Never log secrets; redact before logging.
45
+ - Sanitize any stored HTML with the orbit-security Sanitizer.
46
+
47
+ ## Module template
48
+
49
+ ```ts
50
+ import { Module } from '@galaxy-stack/orbit-core';
51
+
52
+ @Module({
53
+ controllers: [UserController],
54
+ providers: [UserService],
55
+ exports: [UserService],
56
+ })
57
+ export class UserModule {}
58
+ ```
59
+
60
+ ## Controller template
61
+
62
+ ```ts
63
+ import { Controller, Get, Post, Body, Param, HttpCode, UseGuards } from '@galaxy-stack/orbit-core';
64
+
65
+ @Controller('users')
66
+ export class UserController {
67
+ constructor(private readonly users: UserService) {}
68
+
69
+ @Get(':id')
70
+ find(@Param('id') id: string) { return this.users.find(id); }
71
+
72
+ @Post()
73
+ @HttpCode(201)
74
+ @UseGuards(JwtAuthGuard)
75
+ create(@Body() body: CreateUserDto) { return this.users.create(body); }
76
+ }
77
+ ```
78
+
79
+ ## GraphQL template
80
+
81
+ ```ts
82
+ import { Resolver, Query, Mutation, Args } from '@galaxy-stack/orbit-graphql';
83
+
84
+ @Resolver()
85
+ export class UserResolver {
86
+ @Query(() => [User])
87
+ users() { return this.userService.list(); }
88
+
89
+ @Mutation(() => User)
90
+ createUser(@Args('input') input: CreateUserInput) {
91
+ return this.userService.create(input);
92
+ }
93
+ }
94
+ ```
95
+
96
+ Module wiring with security limits:
97
+
98
+ ```ts
99
+ GraphQLModule.forRoot({
100
+ autoSchemaFile: true,
101
+ introspection: process.env.NODE_ENV !== 'production',
102
+ security: { maxDepth: 10, maxComplexity: 1000, maxAliases: 30 },
103
+ resolvers: [UserResolver],
104
+ })
105
+ ```
106
+
107
+ ## Verification checklist (run before declaring done)
108
+
109
+ 1. `bun test` passes.
110
+ 2. App boots: `bun run dev` shows no startup errors.
111
+ 3. Mutating routes have validation + auth.
112
+ 4. GraphQL module has security limits when used.
113
+ 5. No secrets in source; config comes from ConfigModule/env.
114
+
115
+ ## Deeper reference
116
+
117
+ Run the companion MCP server (`@galaxy-stack/orbit-mcp`) for searchable
118
+ knowledge, scaffolding tools, and a security review tool:
119
+
120
+ ```json
121
+ {
122
+ "mcpServers": {
123
+ "orbit": { "command": "bunx", "args": ["@galaxy-stack/orbit-mcp"] }
124
+ }
125
+ }
126
+ ```