@c9up/nebula 0.1.0 → 0.1.1

package/README.md

@@ -40,9 +40,15 @@ ream nebula:add dialog data-table   # copies both, plus what they depend on
 ream nebula:add button --force      # overwrite your edited copy
 ```
 
-Subcommands on the ream binary, not a CLI of nebula's own — the same place
-`ream nova:vapid:generate` lives. The registry logic stays in this package; the
-binary dispatches to it.
+Command classes shipped by this package and registered in `reamrc.commands` by
+`configure()` — the channel Ream provides for exactly this, which directory
+discovery cannot see. `ream` forwards any unrecognised name to the app's
+console kernel, so nothing is compiled into the binary and a new nebula command
+never waits on a release of it.
+
+Like atlas's seven migration commands, and for the same reason, this needs no
+dependency on `@c9up/ream`: `src/console/contract.ts` declares the shape the
+kernel dispatches against rather than importing it.
 
 Copies mirror the package's own layout, so `atoms/Button` finds `../lib/cva.js` for the same reason it does inside nebula. **No import is ever rewritten** — that is where a copy-the-source CLI usually accumulates its edge cases.
 

package/dist/configure.d.ts

@@ -27,6 +27,8 @@ interface Codemods {
     writeFile(filePath: string, content: string, options?: {
         force?: boolean;
     }): Promise<void>;
+    /** Appends to `reamrc.commands` — the channel for package-shipped commands. */
+    registerCommand(importPath: string): Promise<void>;
 }
 /** Flags forwarded from `ream add` / `ream configure`, as the CLI encodes them. */
 type Flags = Record<string, string[] | undefined>;

package/dist/configure.js

@@ -59,6 +59,12 @@ export async function configure(codemods, flags = {}) {
     const adapter = adapterFor(name);
     const config = resolveConfig({ adapter: name });
     await codemods.writeFile("config/nebula.ts", configFile(name));
+    // `reamrc.commands` is the channel Ream provides for commands a package
+    // ships, which directory discovery cannot see. `ream` forwards any
+    // unrecognised name to the app's console kernel, so these exist without a
+    // line of Rust and without waiting on a release of the binary.
+    await codemods.registerCommand("@c9up/nebula/commands/add");
+    await codemods.registerCommand("@c9up/nebula/commands/list");
     for (const file of adapter.files(config)) {
         await codemods.writeFile(file.path, file.contents);
     }

package/dist/console/AddCommand.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `ream nebula:add <component…>` — copy components into the project.
+ *
+ * A command class registered through `reamrc.commands`, which is the channel
+ * Ream provides for commands a package ships and directory discovery cannot
+ * see. `ream` dispatches any unrecognised name to the app's console kernel,
+ * so nothing has to be added to the binary for this to exist.
+ *
+ * That matters more than it looks: the alternative — a subcommand compiled
+ * into `ream-cli` — makes every package that wants a command wait on a release
+ * of a Rust binary, and that binary is not on crates.io.
+ */
+export default class NebulaAddCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    static args: import("./contract.js").ArgumentMetaData[];
+    static flags: import("./contract.js").FlagMetaData[];
+    static help: string[];
+    components: string[];
+    force: boolean;
+    dryRun: boolean;
+    ts: boolean;
+    js: boolean;
+    run(): Promise<void>;
+}

package/dist/console/AddCommand.js

@@ -0,0 +1,84 @@
+/**
+ * `ream nebula:add <component…>` — copy components into the project.
+ *
+ * A command class registered through `reamrc.commands`, which is the channel
+ * Ream provides for commands a package ships and directory discovery cannot
+ * see. `ream` dispatches any unrecognised name to the app's console kernel,
+ * so nothing has to be added to the binary for this to exist.
+ *
+ * That matters more than it looks: the alternative — a subcommand compiled
+ * into `ream-cli` — makes every package that wants a command wait on a release
+ * of a Rust binary, and that binary is not on crates.io.
+ */
+import { add } from "../cli/add.js";
+import { argument, flag } from "./contract.js";
+export default class NebulaAddCommand {
+    static commandName = "nebula:add";
+    static description = "Copy nebula components into the project — they become yours to edit";
+    // Files only; nothing here needs the container or a booted app.
+    static options = { startApp: false };
+    static args = [
+        argument("components", {
+            type: "spread",
+            description: "Component names, as `ream nebula:list` prints them",
+        }),
+    ];
+    static flags = [
+        flag("force", "boolean", {
+            description: "Overwrite files that already exist",
+        }),
+        flag("dryRun", "boolean", {
+            description: "Print what would happen and write nothing",
+        }),
+        flag("ts", "boolean", {
+            description: "Copy TypeScript sources instead of the compiled output",
+        }),
+        flag("js", "boolean", {
+            description: "Copy the compiled JavaScript (the default for an unbuilt app)",
+        }),
+    ];
+    static help = [
+        "  ream nebula:add button card",
+        "  ream nebula:add dialog --force",
+        "",
+        "Components are copied, not linked. Once they are in your project they are",
+        "yours: edit the class strings, delete what you do not use, and nothing",
+        "upgrades them behind your back.",
+    ];
+    components = [];
+    force = false;
+    dryRun = false;
+    ts = false;
+    js = false;
+    async run() {
+        if (this.components.length === 0) {
+            process.stderr.write("Name at least one component — `ream nebula:add button`.\n" +
+                "`ream nebula:list` shows what the registry holds.\n");
+            process.exitCode = 1;
+            return;
+        }
+        const result = add({
+            cwd: process.cwd(),
+            names: this.components,
+            force: this.force,
+            dryRun: this.dryRun,
+            language: this.ts ? "ts" : this.js ? "js" : undefined,
+        });
+        const out = [""];
+        for (const path of result.written)
+            out.push(`  create  ${path}`);
+        for (const path of result.skipped)
+            out.push(`  exists  ${path}`);
+        if (result.skipped.length > 0) {
+            out.push("", "  Existing files were left alone. Re-run with --force to overwrite.");
+        }
+        // Stated rather than assumed: the language is inferred from the tree in
+        // most runs, and copying the wrong one writes files the project cannot
+        // load — a silent failure worth one line to prevent.
+        out.push("", `  Copied as ${result.language === "ts" ? "TypeScript" : "JavaScript"}. Override with --ts or --js.`, "");
+        process.stdout.write(out.join("\n"));
+    }
+}
+// Fails the build if the class drifts from what the kernel dispatches against.
+const _contract = NebulaAddCommand;
+void _contract;

package/dist/console/ListCommand.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `ream nebula:list` — show what the registry holds.
+ *
+ * Reads `registry.json` out of the installed package, which is why this lives
+ * here and not in the binary: the CLI can neither resolve where nebula is
+ * installed nor parse a format that belongs to this repo.
+ */
+export default class NebulaListCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    static flags: import("./contract.js").FlagMetaData[];
+    layer?: string;
+    run(): Promise<void>;
+}

package/dist/console/ListCommand.js

@@ -0,0 +1,49 @@
+/**
+ * `ream nebula:list` — show what the registry holds.
+ *
+ * Reads `registry.json` out of the installed package, which is why this lives
+ * here and not in the binary: the CLI can neither resolve where nebula is
+ * installed nor parse a format that belongs to this repo.
+ */
+import { join } from "node:path";
+import { loadRegistry, packageRoot } from "../cli/registry.js";
+import { flag } from "./contract.js";
+const LAYERS = ["atoms", "molecules", "organisms", "templates"];
+export default class NebulaListCommand {
+    static commandName = "nebula:list";
+    static description = "List the nebula components available to `ream nebula:add`";
+    static options = { startApp: false };
+    static flags = [
+        flag("layer", "string", {
+            description: `Restrict to one atomic layer (${LAYERS.join(", ")})`,
+        }),
+    ];
+    layer;
+    async run() {
+        const root = packageRoot(join(process.cwd(), "package.json"));
+        const registry = loadRegistry(join(root, "registry.json"));
+        if (this.layer !== undefined &&
+            !LAYERS.some((name) => name === this.layer)) {
+            // Named but unknown: a typo would otherwise print nothing at all and
+            // read as "the registry is empty".
+            process.stderr.write(`Unknown layer "${this.layer}" — one of ${LAYERS.join(", ")}.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const out = [];
+        for (const layer of LAYERS) {
+            if (this.layer !== undefined && this.layer !== layer)
+                continue;
+            const names = registry.items
+                .filter((item) => item.layer === layer)
+                .map((item) => item.name);
+            if (names.length === 0)
+                continue;
+            out.push("", `  ${layer} (${names.length})`, `  ${names.join(", ")}`);
+        }
+        out.push("");
+        process.stdout.write(out.join("\n"));
+    }
+}
+const _contract = NebulaListCommand;
+void _contract;

package/dist/console/contract.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The console-command contract, declared locally.
+ *
+ * nebula must not import `@c9up/ream`. It is a component package whose only
+ * peer is aurora, and taking on the framework to describe two commands would
+ * be the tail wagging the dog. Atlas reached the same conclusion for its seven
+ * migration commands and declares the same shape in its own `contract.ts`;
+ * this is that decision, repeated because the reason is the same.
+ *
+ * What the kernel actually needs is structural: a class with `commandName`,
+ * `description` and a `run()`, plus the metadata it reads to parse argv into
+ * instance properties. Ream's `@args` / `@flags` decorators build that
+ * metadata; these helpers build the identical shape without them.
+ */
+export interface CommandOptions {
+    /** Boot the application before `run()`. Off — nebula touches only files. */
+    startApp?: boolean;
+    staysAlive?: boolean;
+    allowUnknownFlags?: boolean;
+}
+export interface ArgumentMetaData {
+    type: "string" | "spread";
+    propertyName: string;
+    argumentName: string;
+    description?: string;
+    required: boolean;
+    default?: string | string[];
+}
+export interface FlagMetaData {
+    type: "string" | "boolean" | "number" | "array";
+    propertyName: string;
+    flagName: string;
+    description?: string;
+    alias: string[];
+    default?: string | string[] | number | boolean;
+    required: boolean;
+}
+/** The static side the kernel reads. */
+export interface NebulaCommandClass {
+    new (): {
+        run(): Promise<void> | void;
+    };
+    commandName: string;
+    description: string;
+    options?: CommandOptions;
+    args?: readonly ArgumentMetaData[];
+    flags?: readonly FlagMetaData[];
+    help?: string | string[];
+}
+export declare function flag(propertyName: string, type: FlagMetaData["type"], options?: {
+    flagName?: string;
+    description?: string;
+    alias?: string[];
+    default?: FlagMetaData["default"];
+    required?: boolean;
+}): FlagMetaData;
+export declare function argument(propertyName: string, options?: {
+    type?: ArgumentMetaData["type"];
+    argumentName?: string;
+    description?: string;
+    required?: boolean;
+    default?: ArgumentMetaData["default"];
+}): ArgumentMetaData;

package/dist/console/contract.js

@@ -0,0 +1,39 @@
+/**
+ * The console-command contract, declared locally.
+ *
+ * nebula must not import `@c9up/ream`. It is a component package whose only
+ * peer is aurora, and taking on the framework to describe two commands would
+ * be the tail wagging the dog. Atlas reached the same conclusion for its seven
+ * migration commands and declares the same shape in its own `contract.ts`;
+ * this is that decision, repeated because the reason is the same.
+ *
+ * What the kernel actually needs is structural: a class with `commandName`,
+ * `description` and a `run()`, plus the metadata it reads to parse argv into
+ * instance properties. Ream's `@args` / `@flags` decorators build that
+ * metadata; these helpers build the identical shape without them.
+ */
+/** `dryRun` → `dry-run`, matching what the framework's decorators produce. */
+function dashCase(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+export function flag(propertyName, type, options = {}) {
+    return {
+        type,
+        propertyName,
+        flagName: options.flagName ?? dashCase(propertyName),
+        description: options.description,
+        alias: options.alias ?? [],
+        default: options.default,
+        required: options.required ?? false,
+    };
+}
+export function argument(propertyName, options = {}) {
+    return {
+        type: options.type ?? "string",
+        propertyName,
+        argumentName: options.argumentName ?? dashCase(propertyName),
+        description: options.description,
+        required: options.required ?? options.default === undefined,
+        default: options.default,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/nebula",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Nebula — shadcn/ui ported to Aurora, organised as atomic design. Zero-dependency headless primitives, cva reimplemented, copy-the-source registry.",
   "license": "MIT",
   "type": "module",
@@ -46,6 +46,14 @@
     "./cli": {
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
+    },
+    "./commands/add": {
+      "types": "./dist/console/AddCommand.d.ts",
+      "import": "./dist/console/AddCommand.js"
+    },
+    "./commands/list": {
+      "types": "./dist/console/ListCommand.d.ts",
+      "import": "./dist/console/ListCommand.js"
     }
   },
   "peerDependencies": {

package/src/configure.ts

@@ -33,6 +33,8 @@ interface Codemods {
 		content: string,
 		options?: { force?: boolean },
 	): Promise<void>;
+	/** Appends to `reamrc.commands` — the channel for package-shipped commands. */
+	registerCommand(importPath: string): Promise<void>;
 }
 
 /** Flags forwarded from `ream add` / `ream configure`, as the CLI encodes them. */
@@ -87,6 +89,14 @@ export async function configure(
 	const config = resolveConfig({ adapter: name });
 
 	await codemods.writeFile("config/nebula.ts", configFile(name));
+
+	// `reamrc.commands` is the channel Ream provides for commands a package
+	// ships, which directory discovery cannot see. `ream` forwards any
+	// unrecognised name to the app's console kernel, so these exist without a
+	// line of Rust and without waiting on a release of the binary.
+	await codemods.registerCommand("@c9up/nebula/commands/add");
+	await codemods.registerCommand("@c9up/nebula/commands/list");
+
 	for (const file of adapter.files(config)) {
 		await codemods.writeFile(file.path, file.contents);
 	}

package/src/console/AddCommand.ts

@@ -0,0 +1,104 @@
+/**
+ * `ream nebula:add <component…>` — copy components into the project.
+ *
+ * A command class registered through `reamrc.commands`, which is the channel
+ * Ream provides for commands a package ships and directory discovery cannot
+ * see. `ream` dispatches any unrecognised name to the app's console kernel,
+ * so nothing has to be added to the binary for this to exist.
+ *
+ * That matters more than it looks: the alternative — a subcommand compiled
+ * into `ream-cli` — makes every package that wants a command wait on a release
+ * of a Rust binary, and that binary is not on crates.io.
+ */
+
+import { add } from "../cli/add.js";
+import { argument, flag, type NebulaCommandClass } from "./contract.js";
+
+export default class NebulaAddCommand {
+	static commandName = "nebula:add";
+	static description =
+		"Copy nebula components into the project — they become yours to edit";
+
+	// Files only; nothing here needs the container or a booted app.
+	static options = { startApp: false };
+
+	static args = [
+		argument("components", {
+			type: "spread",
+			description: "Component names, as `ream nebula:list` prints them",
+		}),
+	];
+
+	static flags = [
+		flag("force", "boolean", {
+			description: "Overwrite files that already exist",
+		}),
+		flag("dryRun", "boolean", {
+			description: "Print what would happen and write nothing",
+		}),
+		flag("ts", "boolean", {
+			description: "Copy TypeScript sources instead of the compiled output",
+		}),
+		flag("js", "boolean", {
+			description:
+				"Copy the compiled JavaScript (the default for an unbuilt app)",
+		}),
+	];
+
+	static help = [
+		"  ream nebula:add button card",
+		"  ream nebula:add dialog --force",
+		"",
+		"Components are copied, not linked. Once they are in your project they are",
+		"yours: edit the class strings, delete what you do not use, and nothing",
+		"upgrades them behind your back.",
+	];
+
+	components: string[] = [];
+	force = false;
+	dryRun = false;
+	ts = false;
+	js = false;
+
+	async run(): Promise<void> {
+		if (this.components.length === 0) {
+			process.stderr.write(
+				"Name at least one component — `ream nebula:add button`.\n" +
+					"`ream nebula:list` shows what the registry holds.\n",
+			);
+			process.exitCode = 1;
+			return;
+		}
+
+		const result = add({
+			cwd: process.cwd(),
+			names: this.components,
+			force: this.force,
+			dryRun: this.dryRun,
+			language: this.ts ? "ts" : this.js ? "js" : undefined,
+		});
+
+		const out: string[] = [""];
+		for (const path of result.written) out.push(`  create  ${path}`);
+		for (const path of result.skipped) out.push(`  exists  ${path}`);
+		if (result.skipped.length > 0) {
+			out.push(
+				"",
+				"  Existing files were left alone. Re-run with --force to overwrite.",
+			);
+		}
+		// Stated rather than assumed: the language is inferred from the tree in
+		// most runs, and copying the wrong one writes files the project cannot
+		// load — a silent failure worth one line to prevent.
+		out.push(
+			"",
+			`  Copied as ${result.language === "ts" ? "TypeScript" : "JavaScript"}. Override with --ts or --js.`,
+			"",
+		);
+		process.stdout.write(out.join("\n"));
+	}
+}
+
+// Fails the build if the class drifts from what the kernel dispatches against.
+const _contract: NebulaCommandClass = NebulaAddCommand;
+void _contract;

package/src/console/ListCommand.ts

@@ -0,0 +1,61 @@
+/**
+ * `ream nebula:list` — show what the registry holds.
+ *
+ * Reads `registry.json` out of the installed package, which is why this lives
+ * here and not in the binary: the CLI can neither resolve where nebula is
+ * installed nor parse a format that belongs to this repo.
+ */
+
+import { join } from "node:path";
+import { loadRegistry, packageRoot } from "../cli/registry.js";
+import { flag, type NebulaCommandClass } from "./contract.js";
+
+const LAYERS = ["atoms", "molecules", "organisms", "templates"] as const;
+
+export default class NebulaListCommand {
+	static commandName = "nebula:list";
+	static description =
+		"List the nebula components available to `ream nebula:add`";
+	static options = { startApp: false };
+
+	static flags = [
+		flag("layer", "string", {
+			description: `Restrict to one atomic layer (${LAYERS.join(", ")})`,
+		}),
+	];
+
+	layer?: string;
+
+	async run(): Promise<void> {
+		const root = packageRoot(join(process.cwd(), "package.json"));
+		const registry = loadRegistry(join(root, "registry.json"));
+
+		if (
+			this.layer !== undefined &&
+			!LAYERS.some((name) => name === this.layer)
+		) {
+			// Named but unknown: a typo would otherwise print nothing at all and
+			// read as "the registry is empty".
+			process.stderr.write(
+				`Unknown layer "${this.layer}" — one of ${LAYERS.join(", ")}.\n`,
+			);
+			process.exitCode = 1;
+			return;
+		}
+
+		const out: string[] = [];
+		for (const layer of LAYERS) {
+			if (this.layer !== undefined && this.layer !== layer) continue;
+			const names = registry.items
+				.filter((item) => item.layer === layer)
+				.map((item) => item.name);
+			if (names.length === 0) continue;
+			out.push("", `  ${layer} (${names.length})`, `  ${names.join(", ")}`);
+		}
+		out.push("");
+		process.stdout.write(out.join("\n"));
+	}
+}
+
+const _contract: NebulaCommandClass = NebulaListCommand;
+void _contract;

package/src/console/contract.ts

@@ -0,0 +1,98 @@
+/**
+ * The console-command contract, declared locally.
+ *
+ * nebula must not import `@c9up/ream`. It is a component package whose only
+ * peer is aurora, and taking on the framework to describe two commands would
+ * be the tail wagging the dog. Atlas reached the same conclusion for its seven
+ * migration commands and declares the same shape in its own `contract.ts`;
+ * this is that decision, repeated because the reason is the same.
+ *
+ * What the kernel actually needs is structural: a class with `commandName`,
+ * `description` and a `run()`, plus the metadata it reads to parse argv into
+ * instance properties. Ream's `@args` / `@flags` decorators build that
+ * metadata; these helpers build the identical shape without them.
+ */
+
+export interface CommandOptions {
+	/** Boot the application before `run()`. Off — nebula touches only files. */
+	startApp?: boolean;
+	staysAlive?: boolean;
+	allowUnknownFlags?: boolean;
+}
+
+export interface ArgumentMetaData {
+	type: "string" | "spread";
+	propertyName: string;
+	argumentName: string;
+	description?: string;
+	required: boolean;
+	default?: string | string[];
+}
+
+export interface FlagMetaData {
+	type: "string" | "boolean" | "number" | "array";
+	propertyName: string;
+	flagName: string;
+	description?: string;
+	alias: string[];
+	default?: string | string[] | number | boolean;
+	required: boolean;
+}
+
+/** The static side the kernel reads. */
+export interface NebulaCommandClass {
+	new (): { run(): Promise<void> | void };
+	commandName: string;
+	description: string;
+	options?: CommandOptions;
+	args?: readonly ArgumentMetaData[];
+	flags?: readonly FlagMetaData[];
+	help?: string | string[];
+}
+
+/** `dryRun` → `dry-run`, matching what the framework's decorators produce. */
+function dashCase(value: string): string {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+export function flag(
+	propertyName: string,
+	type: FlagMetaData["type"],
+	options: {
+		flagName?: string;
+		description?: string;
+		alias?: string[];
+		default?: FlagMetaData["default"];
+		required?: boolean;
+	} = {},
+): FlagMetaData {
+	return {
+		type,
+		propertyName,
+		flagName: options.flagName ?? dashCase(propertyName),
+		description: options.description,
+		alias: options.alias ?? [],
+		default: options.default,
+		required: options.required ?? false,
+	};
+}
+
+export function argument(
+	propertyName: string,
+	options: {
+		type?: ArgumentMetaData["type"];
+		argumentName?: string;
+		description?: string;
+		required?: boolean;
+		default?: ArgumentMetaData["default"];
+	} = {},
+): ArgumentMetaData {
+	return {
+		type: options.type ?? "string",
+		propertyName,
+		argumentName: options.argumentName ?? dashCase(propertyName),
+		description: options.description,
+		required: options.required ?? options.default === undefined,
+		default: options.default,
+	};
+}