create-hazejs 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present hazejs contributors
+
+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,3 +1,18 @@
-# Temporary Holding Version
+# create-hazejs
 
-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.
+Create a new hazejs project.
+
+## Usage
+
+```bash
+pnpm create hazejs my-app            # interactive
+pnpm create hazejs my-app -t api     # backend-only API
+pnpm create hazejs my-app -t vue     # Vue 3 full-stack
+pnpm create hazejs my-app -t react   # React 19 full-stack
+```
+
+Part of [hazejs](https://github.com/penna-org/haze) — see the main README for documentation.
+
+## License
+
+[MIT](./LICENSE)

package/bin/create-hazejs.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.mjs'

package/dist/index.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/index.mjs

@@ -0,0 +1,74 @@
+import { TEMPLATES, scaffold } from "./scaffold.mjs";
+import { relative } from "node:path";
+import process from "node:process";
+import { defineCommand, runMain } from "citty";
+import { consola } from "consola";
+import { colors } from "consola/utils";
+// src/index.ts
+const main = defineCommand({
+	meta: {
+		name: "create-hazejs",
+		description: "创建 hazejs 项目"
+	},
+	args: {
+		dir: {
+			type: "positional",
+			description: "项目目录",
+			required: false
+		},
+		template: {
+			type: "string",
+			alias: "t",
+			description: `模板：${Object.keys(TEMPLATES).join(" | ")}`
+		},
+		force: {
+			type: "boolean",
+			description: "目标目录非空时覆盖",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const interactive = process.stdin.isTTY && !process.env.CI;
+		let dir = args.dir;
+		if (!dir && interactive) dir = await consola.prompt("项目名称", {
+			type: "text",
+			placeholder: "my-app",
+			cancel: "reject"
+		});
+		if (!dir) throw new Error("请指定项目目录，例如：create-hazejs my-app");
+		let template = args.template;
+		if (!template && interactive) template = await consola.prompt("选择模板", {
+			type: "select",
+			options: Object.entries(TEMPLATES).map(([value, hint]) => ({
+				value,
+				label: value,
+				hint
+			})),
+			cancel: "reject"
+		});
+		template ??= "api";
+		const result = scaffold({
+			dir,
+			template,
+			force: args.force
+		});
+		const pm = detectPackageManager();
+		const cd = relative(process.cwd(), result.root) || ".";
+		consola.success(`已创建 ${colors.cyan(result.name)}（${template} 模板，${result.files.length} 个文件）`);
+		consola.log(`
+  下一步：
+
+    ${cd === "." ? "" : `cd ${cd}\n    `}${pm} install
+    ${pm === "npm" ? "npm run" : pm} dev
+`);
+	}
+});
+function detectPackageManager() {
+	const agent = process.env.npm_config_user_agent ?? "";
+	if (agent.startsWith("pnpm")) return "pnpm";
+	if (agent.startsWith("yarn")) return "yarn";
+	if (agent.startsWith("bun")) return "bun";
+	return "npm";
+}
+runMain(main);
+export {};

package/dist/scaffold.d.mts

@@ -0,0 +1,29 @@
+export declare const TEMPLATES: {
+  readonly api: "纯后端 API 服务";
+  readonly vue: "Vue 3 全栈（同仓库、同端口、一次构建）";
+  readonly react: "React 19 全栈（同仓库、同端口、一次构建）";
+};
+export type TemplateName = keyof typeof TEMPLATES;
+export interface ScaffoldOptions {
+  /** 目标目录 */
+  dir: string;
+  template: TemplateName;
+  /** 项目名（package.json name），默认取目录名 */
+  name?: string;
+  /** 框架包的版本范围，默认使用 create-hazejs 自身的版本 */
+  version?: string;
+  /** 目标目录非空时清空 */
+  force?: boolean;
+  /**
+   * 生成 pnpm-workspace.yaml（声明依赖安装脚本的处理，pnpm 11 未声明时安装会报错）。
+   * 默认只在目标目录不位于已有 pnpm workspace 中时生成，避免嵌套 workspace
+   */
+  pnpmWorkspace?: boolean;
+}
+export interface ScaffoldResult {
+  root: string;
+  name: string;
+  files: string[];
+}
+export declare function scaffold(options: ScaffoldOptions): ScaffoldResult;
+export declare function toPackageName(input: string): string;

package/dist/scaffold.mjs

@@ -0,0 +1,76 @@
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { Buffer } from "node:buffer";
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+// src/scaffold.ts
+const TEMPLATES = {
+	api: "纯后端 API 服务",
+	vue: "Vue 3 全栈（同仓库、同端口、一次构建）",
+	react: "React 19 全栈（同仓库、同端口、一次构建）"
+};
+const templatesDir = fileURLToPath(new URL("../templates", import.meta.url));
+/** npm 发布时会丢弃 .gitignore，模板中以 _gitignore 存放 */
+const RENAMES = { _gitignore: ".gitignore" };
+/**
+* pnpm 11 要求显式声明是否运行依赖的安装脚本，未声明时 install / run 会报错。
+* esbuild（drizzle-kit、tsx 引入）的二进制来自平台可选依赖，不需要运行安装脚本
+*/
+const PNPM_WORKSPACE = `# pnpm 11：依赖的安装脚本需要显式允许或忽略（新增需要构建的依赖时在此声明）
+allowBuilds:
+  esbuild: false
+`;
+function scaffold(options) {
+	const root = resolve(options.dir);
+	const source = join(templatesDir, options.template);
+	if (!existsSync(source)) throw new Error(`Unknown template "${options.template}". Available: ${Object.keys(TEMPLATES).join(", ")}`);
+	if (existsSync(root) && readdirSync(root).length) {
+		if (!options.force) throw new Error(`Target directory ${root} is not empty. Use --force to overwrite.`);
+		rmSync(root, {
+			recursive: true,
+			force: true
+		});
+	}
+	const name = toPackageName(options.name ?? basename(root));
+	const variables = {
+		name,
+		version: options.version ?? `^${ownVersion()}`,
+		appKey: Buffer.from(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32))).toString("base64url")
+	};
+	cpSync(source, root, { recursive: true });
+	const files = walk(root);
+	for (const file of files) {
+		const content = readFileSync(file, "utf8");
+		const replaced = content.replace(/\{\{(\w+)\}\}/g, (match, key) => variables[key] ?? match);
+		if (replaced !== content) writeFileSync(file, replaced);
+	}
+	for (const file of files) {
+		const target = RENAMES[basename(file)];
+		if (target) renameSync(file, join(file, "..", target));
+	}
+	if (options.pnpmWorkspace ?? !findPnpmWorkspace(dirname(root))) writeFileSync(join(root, "pnpm-workspace.yaml"), PNPM_WORKSPACE);
+	return {
+		root,
+		name,
+		files: walk(root).map((file) => relative(root, file)).sort()
+	};
+}
+/** 向上查找所在的 pnpm workspace 根目录 */
+function findPnpmWorkspace(from) {
+	for (let dir = from;; dir = dirname(dir)) {
+		if (existsSync(join(dir, "pnpm-workspace.yaml"))) return dir;
+		if (dirname(dir) === dir) return void 0;
+	}
+}
+function toPackageName(input) {
+	return input.trim().toLowerCase().replace(/\s+/g, "-").replace(/^[._]+/, "").replace(/[^a-z0-9\-~]+/g, "-") || "hazejs-app";
+}
+function walk(dir) {
+	return readdirSync(dir).flatMap((entry) => {
+		const path = join(dir, entry);
+		return statSync(path).isDirectory() ? walk(path) : [path];
+	});
+}
+function ownVersion() {
+	return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+}
+export { TEMPLATES, scaffold, toPackageName };

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "create-hazejs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.1.1",
+  "description": "Create a hazejs project (API, Vue or React full-stack)",
+  "license": "MIT",
+  "homepage": "https://github.com/penna-org/haze/tree/main/packages/create#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/penna-org/haze.git",
+    "directory": "packages/create"
+  },
+  "bugs": {
+    "url": "https://github.com/penna-org/haze/issues"
+  },
+  "keywords": [
+    "hazejs",
+    "haze",
+    "nodejs",
+    "typescript",
+    "create",
+    "scaffold",
+    "template",
+    "starter"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/scaffold.d.mts",
+      "default": "./dist/scaffold.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "create-hazejs": "./bin/create-hazejs.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "consola": "^3.4.2"
+  },
+  "devDependencies": {
+    "@libsql/client": "^0.18.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "bullmq": "^6.5.0",
+    "deno": "^2.9.6",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.4",
+    "ioredis": "^6.0.0",
+    "miniflare": "^4.20260730.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "socket.io": "^4.8.4",
+    "socket.io-client": "^4.8.4",
+    "typescript": "~6.0.3",
+    "valibot": "^1.1.0",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "vue": "^3.5.44",
+    "vue-tsc": "^3.3.13",
+    "@hazejs/cli": "0.1.1",
+    "@hazejs/core": "0.1.1",
+    "@hazejs/orm": "0.1.1",
+    "@hazejs/socket.io": "0.1.1",
+    "@hazejs/testing": "0.1.1",
+    "@hazejs/vite": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }

package/templates/api/.env

@@ -0,0 +1,4 @@
+APP_NAME={{name}}
+DATABASE_URL=file:./data/app.db
+# 应用密钥（签名 Cookie、加密 Session、JWT），泄露后用 haze key:generate --force 更换
+APP_KEY={{appKey}}

package/templates/api/.env.test

@@ -0,0 +1 @@
+DATABASE_URL=:memory: