create-nubis 0.0.0 → 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EYTAK LIMITED
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,9 @@
 # create-nubis
 
-**Nubis** is a Discord bot framework in development: file-based commands, types inferred from your definitions, typed components, built-in testing and one-command deploys.
+Start a [Nubis](https://eytak.com/nubis) Discord bot:
 
-Coming soon. Built by [Eytak](https://eytak.com).
+```sh
+npx create-nubis my-bot
+```
+
+MIT. Built by [Eytak](https://eytak.com).

package/dist/create.d.ts

@@ -0,0 +1,12 @@
+import { type PackageManager } from "./templates";
+export interface CreateOptions {
+    readonly name: string;
+    readonly packageManager: PackageManager;
+    readonly nubisVersion: string;
+}
+/** Writes a new bot into `dir`, which must be missing or empty. Returns the files written. */
+export declare function createProject(dir: string, options: CreateOptions): Promise<string[]>;
+/** The package manager that ran create-nubis (npx, bunx, pnpm create…), from npm_config_user_agent. */
+export declare function detectPackageManager(userAgent: string | undefined): PackageManager;
+/** `^0.1.0` for released versions; "latest" while developing (0.0.0). */
+export declare function nubisRange(version: string): string;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { resolve } from "node:path";
+// package.json
+var package_default = {
+  name: "create-nubis",
+  version: "0.1.0-next.0",
+  description: "Scaffold a new Nubis Discord bot. Built by Eytak.",
+  keywords: [
+    "discord",
+    "discord-bot",
+    "nubis",
+    "create"
+  ],
+  license: "MIT",
+  author: "Eytak",
+  homepage: "https://eytak.com/nubis",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Eytak-Technologies/nubis.git",
+    directory: "packages/create-nubis"
+  },
+  bugs: "https://github.com/Eytak-Technologies/nubis/issues",
+  type: "module",
+  bin: {
+    "create-nubis": "./dist/index.js"
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  scripts: {
+    build: "bun build ./src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    test: "bun test",
+    lint: "biome lint ."
+  },
+  devDependencies: {
+    nubis: "workspace:*"
+  }
+};
+
+// src/create.ts
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+// src/templates.ts
+var json = (value) => `${JSON.stringify(value, null, "\t")}
+`;
+function templateFiles(options) {
+  const { name, packageManager, nubisVersion } = options;
+  const bun = packageManager === "bun";
+  const run = packageManager === "npm" ? "npm run" : packageManager;
+  const testImport = bun ? "bun:test" : "vitest";
+  return {
+    "package.json": json({
+      name,
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "nubis dev",
+        start: "nubis start",
+        sync: "nubis sync --global",
+        test: bun ? "bun test" : "vitest run",
+        typecheck: "tsc --noEmit"
+      },
+      dependencies: { nubis: nubisVersion },
+      devDependencies: bun ? { "@types/bun": "^1.4.4", typescript: "^7.0.0" } : { "@types/node": "^22.0.0", typescript: "^7.0.0", vitest: "^5.1.0" }
+    }),
+    "tsconfig.json": json({
+      compilerOptions: {
+        target: "ES2022",
+        module: "Preserve",
+        moduleResolution: "bundler",
+        types: [bun ? "bun" : "node"],
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        verbatimModuleSyntax: true,
+        noUncheckedIndexedAccess: true
+      },
+      include: ["**/*.ts"]
+    }),
+    "nubis.config.ts": `import { defineConfig } from "nubis";
+
+// Settings for the whole bot. Every key is optional; see https://eytak.com/nubis/docs/configuration
+export default defineConfig({
+	presence: { activity: { type: "watching", name: "for /ping" } },
+});
+`,
+    ".gitignore": `node_modules
+dist
+.env
+`,
+    ".env.example": `# From https://discord.com/developers/applications, under your app.
+DISCORD_TOKEN=
+DISCORD_APPLICATION_ID=
+DISCORD_PUBLIC_KEY=
+`,
+    "README.md": `# ${name}
+
+A Discord bot built with [Nubis](https://eytak.com/nubis). Docs: https://eytak.com/nubis/docs
+
+## Getting started
+
+1. Create an application at https://discord.com/developers/applications and add a bot.
+2. Copy \`.env.example\` to \`.env\` and fill it in.
+3. Run the tests: \`${run} test\`
+4. Start the bot: \`${run} dev\`
+
+## Deploying
+
+\`${run} sync\` registers your commands everywhere the bot is installed; run it when commands change. \`${run} start\` runs the bot.
+
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| \`commands/ping.ts\` | \`/ping\`, the smallest command |
+| \`commands/echo.ts\` | \`/echo\`, with a required option |
+| \`commands/fun/roll.ts\` | \`/fun roll\`: folders become subcommands; \`_folder.ts\` describes them |
+| \`commands/counter.ts\`, \`components/counter.ts\` | A button that keeps its count in typed state |
+| \`events/ready.ts\` | Runs when the bot connects |
+| \`nubis.config.ts\` | Bot-wide settings: presence, intents, guards, error handling |
+| \`tests/\` | Tests that run without Discord, using \`nubis/testing\` |
+`,
+    "commands/ping.ts": `import { command } from "nubis";
+
+export default command({
+	description: "Check that the bot is alive",
+	run: ({ reply }) => reply("Pong!"),
+});
+`,
+    "commands/echo.ts": `import { command, option } from "nubis";
+
+export default command({
+	description: "Repeat something back to you",
+	ephemeral: true,
+	options: {
+		text: option.string({ description: "What to repeat", required: true, maxLength: 200 }),
+	},
+	// options.text is a string: required options are never undefined.
+	run: ({ options, reply }) => reply(options.text),
+});
+`,
+    "commands/fun/_folder.ts": `import { folder } from "nubis";
+
+export default folder({ description: "Games and silly things" });
+`,
+    "commands/fun/roll.ts": `import { command, option } from "nubis";
+
+export default command({
+	description: "Roll a die",
+	options: {
+		sides: option.integer({
+			description: "How many sides",
+			choices: [
+				{ name: "Six", value: 6 },
+				{ name: "Twenty", value: 20 },
+			],
+		}),
+	},
+	// options.sides is 6 | 20 | undefined, from the choices.
+	run: ({ options, reply }) => {
+		const sides = options.sides ?? 6;
+		return reply(\`\uD83C\uDFB2 You rolled \${1 + Math.floor(Math.random() * sides)} (d\${sides})\`);
+	},
+});
+`,
+    "commands/counter.ts": `import { command } from "nubis";
+import { counter } from "../components/counter";
+
+export default command({
+	description: "A button that counts clicks",
+	run: ({ reply }) => reply({ content: "Clicked 0 times", components: [counter({ count: 0 })] }),
+});
+`,
+    "components/counter.ts": `import { button, stateOf } from "nubis";
+
+// The count travels in the button's custom_id, so no database is needed.
+// For state you act on (user ids, amounts), use a schema such as Zod instead
+// of stateOf: anyone can craft a custom_id, and schemas validate every click.
+export const counter = button({
+	id: "counter",
+	label: "Click me",
+	style: "primary",
+	state: stateOf<{ count: number }>(),
+	onClick: ({ state, update }) => {
+		const count = state.count + 1;
+		return update({ content: \`Clicked \${count} times\`, components: [counter({ count })] });
+	},
+});
+`,
+    "events/ready.ts": `import { event } from "nubis";
+
+export default event("ready", (data) => {
+	console.log(\`Logged in as \${data.user.username}\`);
+});
+`,
+    "tests/commands.test.ts": `import { describe, expect, test } from "${testImport}";
+import { fake, testCommand, testComponent } from "nubis/testing";
+import { counter } from "../components/counter";
+import echo from "../commands/echo";
+import ping from "../commands/ping";
+
+describe("commands", () => {
+	test("/ping answers", async () => {
+		const result = await testCommand(ping).run();
+		expect(result.replies).toEqual(["Pong!"]);
+	});
+
+	test("/echo repeats privately", async () => {
+		const result = await testCommand(echo).as({ user: fake.user("alice") }).run({ text: "hello" });
+		expect(result.replies).toEqual(["hello"]);
+		expect(result.ephemeral).toBe(true);
+	});
+
+	test("the counter counts", async () => {
+		const result = await testComponent(counter).click({ count: 41 });
+		expect(result.replies).toEqual(["Clicked 42 times"]);
+	});
+});
+`
+  };
+}
+
+// src/create.ts
+async function createProject(dir, options) {
+  const existing = await readdir(dir).catch(() => []);
+  if (existing.length > 0) {
+    throw new Error(`${dir} isn't empty. Pick a new folder name, or empty this one first.`);
+  }
+  const files = templateFiles(options);
+  for (const [path, content] of Object.entries(files)) {
+    await mkdir(dirname(join(dir, path)), { recursive: true });
+    await writeFile(join(dir, path), content);
+  }
+  return Object.keys(files);
+}
+function detectPackageManager(userAgent) {
+  const name = userAgent?.split("/")[0];
+  return name === "bun" || name === "pnpm" || name === "yarn" ? name : "npm";
+}
+function nubisRange(version) {
+  return version === "0.0.0" ? "latest" : `^${version}`;
+}
+
+// src/project-name.ts
+var VALID_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+function resolveProjectName(args) {
+  const name = args.find((arg) => !arg.startsWith("-")) ?? "my-bot";
+  if (!VALID_NAME.test(name)) {
+    throw new Error(`"${name}" is not a valid package name. Use lowercase letters, digits and dashes.`);
+  }
+  return name;
+}
+
+// src/index.ts
+var MANAGERS = ["bun", "npm", "pnpm", "yarn"];
+function flag(args, name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+async function main(args) {
+  const pmFlag = flag(args, "--pm");
+  if (pmFlag !== undefined && !MANAGERS.includes(pmFlag)) {
+    throw new Error(`--pm must be one of ${MANAGERS.join(", ")}.`);
+  }
+  const packageManager = pmFlag ?? detectPackageManager(process.env.npm_config_user_agent);
+  const name = resolveProjectName(args.filter((arg, i) => !(args[i - 1] === "--pm") && arg !== "--pm"));
+  const dir = resolve(name);
+  await createProject(dir, {
+    name: name.split("/").at(-1) ?? name,
+    packageManager,
+    nubisVersion: nubisRange(package_default.version)
+  });
+  const run = packageManager === "npm" ? "npm run" : packageManager;
+  console.log(`
+Created ${name} with Nubis.
+
+  cd ${name}
+  ${packageManager} install
+  ${run} test
+
+Then add your bot's token to .env (see .env.example) and run \`${run} dev\`.
+`);
+}
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/dist/project-name.d.ts

@@ -0,0 +1 @@
+export declare function resolveProjectName(args: readonly string[]): string;

package/dist/templates.d.ts

@@ -0,0 +1,9 @@
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+export interface TemplateOptions {
+    readonly name: string;
+    readonly packageManager: PackageManager;
+    /** The `nubis` version range to depend on. */
+    readonly nubisVersion: string;
+}
+/** The files of a new bot, by path. Bun projects test with bun:test, others with Vitest. */
+export declare function templateFiles(options: TemplateOptions): Record<string, string>;

package/package.json

@@ -1,9 +1,39 @@
 {
-  "name": "create-nubis",
-  "version": "0.0.0",
-  "description": "Scaffold a new Nubis Discord bot. Built by Eytak.",
-  "keywords": ["discord", "discord-bot", "framework", "nubis"],
-  "homepage": "https://eytak.com",
-  "author": "Eytak",
-  "files": ["README.md"]
+	"name": "create-nubis",
+	"version": "0.1.0-next.0",
+	"description": "Scaffold a new Nubis Discord bot. Built by Eytak.",
+	"keywords": [
+		"discord",
+		"discord-bot",
+		"nubis",
+		"create"
+	],
+	"license": "MIT",
+	"author": "Eytak",
+	"homepage": "https://eytak.com/nubis",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Eytak-Technologies/nubis.git",
+		"directory": "packages/create-nubis"
+	},
+	"bugs": "https://github.com/Eytak-Technologies/nubis/issues",
+	"type": "module",
+	"bin": {
+		"create-nubis": "./dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"build": "bun build ./src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+		"check-types": "tsc --noEmit",
+		"test": "bun test",
+		"lint": "biome lint ."
+	},
+	"devDependencies": {
+		"nubis": "0.1.0-next.0"
+	}
 }