@skyroc/scripts 2.5.0

package/dist/config-BKkdncJS.mjs

@@ -0,0 +1,987 @@
+import { createRequire } from "node:module";
+import { generateChangelog, generateTotalChangelog } from "@soybeanjs/changelog";
+import { rimraf } from "rimraf";
+import { existsSync, readFileSync } from "node:fs";
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { bgRed, cyan, green, red, yellow } from "kolorist";
+import { fileURLToPath } from "node:url";
+import enquirer from "enquirer";
+import { versionBump } from "bumpp";
+import { tmpdir } from "node:os";
+import { parseYAML } from "confbox";
+import { loadConfig } from "c12";
+
+//#region src/commands/changelog.ts
+async function genChangelog(options, total = false) {
+	if (total) await generateTotalChangelog(options);
+	else await generateChangelog(options);
+}
+
+//#endregion
+//#region src/commands/cleanup.ts
+async function cleanup(paths) {
+	await rimraf(paths, { glob: true });
+}
+
+//#endregion
+//#region src/shared/index.ts
+async function execCommand(cmd, args, options) {
+	const { execa } = await import("execa");
+	return ((await execa(cmd, args, options))?.stdout)?.trim() || "";
+}
+/** 从当前模块位置向上找到 `@skyroc/scripts` 自身的包根，用于定位内置 templates。 */
+function getPackageRoot() {
+	let currentDir = path.dirname(fileURLToPath(import.meta.url));
+	while (currentDir !== path.dirname(currentDir)) {
+		if (existsSync(path.join(currentDir, "package.json"))) return currentDir;
+		currentDir = path.dirname(currentDir);
+	}
+	throw new Error("Cannot resolve @skyroc/scripts package root.");
+}
+/** 从 cwd 向上找到 monorepo 根目录。只有仓库内的命令才需要它。 */
+function getWorkspaceRoot(startDir = process.cwd()) {
+	let currentDir = path.resolve(startDir);
+	while (currentDir !== path.dirname(currentDir)) {
+		if (existsSync(path.join(currentDir, "pnpm-workspace.yaml"))) return currentDir;
+		currentDir = path.dirname(currentDir);
+	}
+	throw new Error("Cannot resolve workspace root. Run this command inside the monorepo.");
+}
+
+//#endregion
+//#region src/template/materialize.ts
+/**
+* 只在 monorepo 内成立的 package.json 字段。生成的是一个全新的私有应用，继承 skyroc-admin 的 homepage / repository /
+* author 只会让新项目一开始就带着错误的身份信息。
+*/
+const DROPPED_PACKAGE_FIELDS = [
+	"author",
+	"bugs",
+	"homepage",
+	"keywords",
+	"repository",
+	"website"
+];
+/**
+* 这些 script 靠 `pnpm --filter` 去构建同一个 workspace 里的 `@skyroc/web-admin-vite`。独立工程里该包直接来自 registry，
+* 已经是构建产物，pre* 钩子只会因为 filter 不到包而失败。
+*/
+const DROPPED_PACKAGE_SCRIPTS = [
+	"build:admin-vite",
+	"prebuild",
+	"prebuild:test",
+	"predev",
+	"predev:prod",
+	"prepreview"
+];
+const STANDALONE_REWRITES = [{
+	file: "vite.config.ts",
+	hint: "vite.config.ts 里没找到 monorepo 的 shellAlias 覆盖块，请同步更新 STANDALONE_REWRITES。",
+	pattern: /,\s*\/\/ monorepo 内 shell 源码[^\n]*\n\s*resolve:\s*\{\s*shellAlias:[^}]*\}/,
+	replacement: ""
+}, {
+	file: "uno.config.ts",
+	hint: "uno.config.ts 的 filesystem 不再是预期的 monorepo 相对路径，请同步更新 STANDALONE_REWRITES。",
+	pattern: /filesystem:\s*\[[^\]]*\]/,
+	replacement: "filesystem: ['./node_modules/@skyroc/web-ui/dist/**/*.{js,mjs,cjs}']"
+}];
+const GITIGNORE = `node_modules
+dist
+dist-ssr
+coverage
+
+.turbo
+.tanstack
+*.tsbuildinfo
+
+.env.local
+.env.*.local
+
+.DS_Store
+*.log
+`;
+function createReadme(packageName, description) {
+	return `# ${packageName}
+
+${description}
+
+基于 [skyroc-admin](https://github.com/Ohh-889/skyroc-admin) 模板，由 \`sa create-admin\` 生成。
+
+## 开始
+
+\`\`\`bash
+pnpm install
+pnpm dev
+\`\`\`
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| \`pnpm dev\` | 启动开发服务器（test 环境变量） |
+| \`pnpm build\` | 生产构建 |
+| \`pnpm preview\` | 预览构建产物 |
+| \`pnpm lint\` | oxlint 检查并自动修复 |
+| \`pnpm typecheck\` | TypeScript 类型检查 |
+
+## 目录
+
+业务页面放在 \`src/pages/(admin)\` 下，路由由 TanStack Router 基于文件结构自动生成。
+`;
+}
+async function materializePackageJson(options) {
+	const { description, meta, packageName, targetDir } = options;
+	const packageJsonPath = path.join(targetDir, "package.json");
+	const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+	packageJson.name = packageName;
+	packageJson.description = description;
+	packageJson.version = "0.0.0";
+	packageJson.private = true;
+	packageJson.dependencies = meta.dependencies;
+	packageJson.devDependencies = meta.devDependencies;
+	for (const field of DROPPED_PACKAGE_FIELDS) delete packageJson[field];
+	const scripts = packageJson.scripts;
+	if (scripts) for (const script of DROPPED_PACKAGE_SCRIPTS) delete scripts[script];
+	if (Object.keys(meta.overrides).length > 0) packageJson.pnpm = { overrides: meta.overrides };
+	await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+async function materializeJsonConfig(targetDir, config) {
+	const content = {
+		$schema: config.schema,
+		...config.content
+	};
+	await writeFile(path.join(targetDir, config.file), `${JSON.stringify(content, null, 2)}\n`);
+}
+/** 返回未命中的重写规则，让调用方决定是告警还是失败。 */
+async function applyStandaloneRewrites(targetDir) {
+	const missed = [];
+	await Promise.all(STANDALONE_REWRITES.map(async (rewrite) => {
+		const filePath = path.join(targetDir, rewrite.file);
+		const content = await readFile(filePath, "utf8");
+		if (!rewrite.pattern.test(content)) {
+			missed.push(rewrite);
+			return;
+		}
+		await writeFile(filePath, content.replace(rewrite.pattern, rewrite.replacement));
+	}));
+	return missed;
+}
+/**
+* shell 源码在生成项目里位于 `src/framework`，monorepo 里位于 `packages/web/admin`。
+* 展平后的 tsconfig 还带着 monorepo 的映射，这里改写成独立工程的路径。
+*/
+function rewriteShellTsconfig(tsconfig) {
+	const rewritten = structuredClone(tsconfig);
+	const paths = (rewritten.compilerOptions ?? {}).paths;
+	if (paths?.["@shell/*"]) paths["@shell/*"] = ["./src/framework/*"];
+	if (Array.isArray(rewritten.include)) rewritten.include = rewritten.include.filter((entry) => typeof entry !== "string" || !entry.includes("packages/web/admin"));
+	return rewritten;
+}
+/**
+* 把同步期解析好的数据套用到生成目录，产出一个脱离 monorepo 也能 install 的应用。
+*
+* 返回需要提醒用户的问题：命中失败的重写规则、以及依赖里仍然指向未发布 workspace 包的部分。这两类问题都不应该静默——
+* 它们最终会以一句莫名其妙的 install 报错砸到用户脸上。
+*/
+async function materializeStandaloneApp(options) {
+	const { description, meta, packageName, targetDir } = options;
+	await materializePackageJson(options);
+	await materializeJsonConfig(targetDir, {
+		content: rewriteShellTsconfig(meta.tsconfig),
+		file: "tsconfig.json",
+		schema: "https://json.schemastore.org/tsconfig"
+	});
+	await materializeJsonConfig(targetDir, {
+		content: meta.oxlintConfig,
+		file: ".oxlintrc.json",
+		schema: "./node_modules/oxlint/configuration_schema.json"
+	});
+	const missedRewrites = await applyStandaloneRewrites(targetDir);
+	await writeFile(path.join(targetDir, ".gitignore"), GITIGNORE);
+	await writeFile(path.join(targetDir, "README.md"), createReadme(packageName, description));
+	return {
+		missedRewrites: missedRewrites.map((rewrite) => `${rewrite.file}: ${rewrite.hint}`),
+		unpublishedPackages: meta.unpublishedPackages
+	};
+}
+
+//#endregion
+//#region src/template/meta.ts
+/** sidecar 文件名，与 `templates/admin/` 平级存放，避免污染快照目录的逐字节比对。 */
+const TEMPLATE_META_FILE = "admin.meta.json";
+/** 按 key 排序，保证同样的输入产出同样的字节，`--check` 才能靠内容比对判断是否落后。 */
+function sortRecord(record) {
+	return Object.fromEntries(Object.entries(record).toSorted(([a], [b]) => a.localeCompare(b)));
+}
+function stringifyTemplateMeta(meta) {
+	const normalized = {
+		dependencies: sortRecord(meta.dependencies),
+		devDependencies: sortRecord(meta.devDependencies),
+		oxlintConfig: meta.oxlintConfig,
+		overrides: sortRecord(meta.overrides),
+		tsconfig: meta.tsconfig,
+		unpublishedPackages: meta.unpublishedPackages.toSorted((a, b) => a.localeCompare(b))
+	};
+	return `${JSON.stringify(normalized, null, 2)}\n`;
+}
+async function readTemplateMeta(metaPath) {
+	const content = await readFile(metaPath, "utf8");
+	return JSON.parse(content);
+}
+
+//#endregion
+//#region src/commands/create-admin.ts
+const TEMPLATE_NAME$1 = "admin";
+function normalizePackageName(name) {
+	const normalizedName = name.trim().replaceAll("_", "-").replace(/\s+/g, "-").replace(/[^a-zA-Z0-9-@/.]/g, "").toLowerCase();
+	if (!normalizedName) throw new Error("Admin app name is required.");
+	if (!/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(normalizedName)) throw new Error(`Invalid package name: ${name}`);
+	return normalizedName;
+}
+function toTitle(name) {
+	return name.replace(/^@[^/]+\//, "").split(/[-_\s]+/).filter(Boolean).map((item) => `${item.charAt(0).toUpperCase()}${item.slice(1)}`).join(" ");
+}
+function toStoragePrefix(name) {
+	return `${name.replace(/^@[^/]+\//, "").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase() || "ADMIN"}_`;
+}
+function getTemplateDir() {
+	return path.join(getPackageRoot(), "templates", TEMPLATE_NAME$1);
+}
+function getShellTemplateDir() {
+	return path.join(getPackageRoot(), "templates", "admin-shell");
+}
+function getTemplateMetaPath() {
+	return path.join(getPackageRoot(), "templates", TEMPLATE_META_FILE);
+}
+async function isDirectoryEmpty(dir) {
+	if (!existsSync(dir)) return true;
+	return (await readdir(dir)).length === 0;
+}
+function replaceEnvValue(content, key, value) {
+	const escapedValue = value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
+	const regexp = new RegExp(`^${key}=.*$`, "m");
+	if (!regexp.test(content)) return `${content.trimEnd()}\n${key}=${escapedValue}\n`;
+	return content.replace(regexp, `${key}=${escapedValue}`);
+}
+async function updatePackageJson(targetDir, packageName, description) {
+	const packageJsonPath = path.join(targetDir, "package.json");
+	const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+	packageJson.name = packageName;
+	packageJson.description = description;
+	await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+async function updateEnvFile(options) {
+	const { description, storagePrefix, targetDir, title } = options;
+	const envPath = path.join(targetDir, ".env");
+	let env = await readFile(envPath, "utf8");
+	env = replaceEnvValue(env, "VITE_APP_TITLE", title);
+	env = replaceEnvValue(env, "VITE_APP_DESC", description);
+	env = replaceEnvValue(env, "VITE_STORAGE_PREFIX", storagePrefix);
+	await writeFile(envPath, env);
+}
+async function installDependencies(cwd) {
+	const { execa } = await import("execa");
+	await execa("pnpm", ["install"], {
+		cwd,
+		stdio: "inherit"
+	});
+}
+/** 独立模式下把 monorepo 协议物化掉，并把物化过程中发现的隐患打印出来。 */
+async function applyStandaloneMaterialization(targetDir, packageName, description) {
+	const metaPath = getTemplateMetaPath();
+	if (!existsSync(metaPath)) throw new Error(`Template metadata is missing: ${metaPath}\nRun "pnpm sa sync-admin-template" to regenerate it, or pass --workspace to keep the monorepo protocols.`);
+	const { missedRewrites, unpublishedPackages } = await materializeStandaloneApp({
+		description,
+		meta: await readTemplateMeta(metaPath),
+		packageName,
+		targetDir
+	});
+	for (const missed of missedRewrites) console.log(yellow(`warning  ${missed}`));
+	if (unpublishedPackages.length > 0) console.log(yellow(`warning  these workspace packages are marked "private": true and cannot be installed from the registry: ${unpublishedPackages.join(", ")}`));
+}
+async function createAdminTemplate(name, options = {}) {
+	const packageName = normalizePackageName(name);
+	const title = options.title || toTitle(packageName);
+	const description = options.description || `${title} admin application`;
+	const storagePrefix = toStoragePrefix(packageName);
+	const directoryName = packageName.replace(/^@[^/]+\//, "");
+	const targetDir = path.resolve(process.cwd(), options.target || path.join("apps", directoryName));
+	const templateDir = getTemplateDir();
+	if (!existsSync(templateDir)) throw new Error(`Admin template is missing: ${templateDir}`);
+	if (existsSync(targetDir) && !await isDirectoryEmpty(targetDir)) {
+		if (!options.force) throw new Error(`Target directory is not empty: ${targetDir}. Use --force to overwrite it.`);
+		await rm(targetDir, {
+			force: true,
+			recursive: true
+		});
+	}
+	await mkdir(path.dirname(targetDir), { recursive: true });
+	await cp(templateDir, targetDir, { recursive: true });
+	if (options.workspace) await updatePackageJson(targetDir, packageName, description);
+	else {
+		const shellTemplateDir = getShellTemplateDir();
+		if (!existsSync(shellTemplateDir)) throw new Error(`Admin shell template is missing: ${shellTemplateDir}\nRun "pnpm sa sync-admin-template" to regenerate it.`);
+		await cp(shellTemplateDir, path.join(targetDir, "src", "framework"), { recursive: true });
+		await applyStandaloneMaterialization(targetDir, packageName, description);
+	}
+	await updateEnvFile({
+		description,
+		storagePrefix,
+		targetDir,
+		title
+	});
+	if (options.install) await installDependencies(options.workspace ? process.cwd() : targetDir);
+	console.log(green(`Created admin app: ${packageName}`));
+	console.log(`${cyan("mode")}   ${options.workspace ? "workspace (monorepo protocols kept)" : "standalone"}`);
+	console.log(`${cyan("target")} ${targetDir}`);
+	if (!options.install) console.log(`${cyan("next")}   ${options.workspace ? "pnpm install (from the workspace root)" : `pnpm --dir ${targetDir} install`}`);
+	console.log(yellow("The template starts with a minimal Home page; add product routes under src/pages/(admin)."));
+}
+
+//#endregion
+//#region src/locales/index.ts
+const locales = {
+	"en-us": {
+		gitCommitMessages: {
+			description: `Please enter a description (add prefix ${yellow("!")} to indicate breaking change)`,
+			emptyDescription: `${bgRed(" ERROR ")} ${red("commit description must not be empty.")}`,
+			scopes: "Please select a scope",
+			types: "Please select a type"
+		},
+		gitCommitScopes: [
+			["projects", "project"],
+			["packages", "packages"],
+			["components", "components"],
+			["hooks", "hook functions"],
+			["utils", "utils functions"],
+			["types", "TS declaration"],
+			["styles", "style"],
+			["deps", "project dependencies"],
+			["release", "release project"],
+			["other", "other changes"]
+		],
+		gitCommitTypes: [
+			["feat", "A new feature"],
+			["feat-wip", "Features in development, such as partial code for a certain feature"],
+			["fix", "A bug fix"],
+			["docs", "Documentation only changes"],
+			["typo", "Code or document corrections, such as spelling errors"],
+			["style", "Changes that do not affect the meaning of the code"],
+			["refactor", "A code change that neither fixes a bug nor adds a feature"],
+			["perf", "A code change that improves performance"],
+			["optimize", "A code change that optimizes code quality"],
+			["test", "Adding missing tests or correcting existing tests"],
+			["build", "Changes that affect the build system or external dependencies"],
+			["ci", "Changes to our CI configuration files and scripts"],
+			["chore", "Other changes that don't modify src or test files"],
+			["revert", "Reverts a previous commit"]
+		],
+		gitCommitVerify: `${bgRed(" ERROR ")} ${red("git commit message must match the Conventional Commits standard!")}\n\n${green("Recommended to use the command `pnpm commit` to generate Conventional Commits compliant commit information.\nGet more info about Conventional Commits, follow this link: https://conventionalcommits.org")}`
+	},
+	"zh-cn": {
+		gitCommitMessages: {
+			description: `请输入描述信息（${yellow("!")}开头表示破坏性改动`,
+			emptyDescription: `${bgRed(" 错误 ")} ${red("提交描述不能为空。")}`,
+			scopes: "请选择提交范围",
+			types: "请选择提交类型"
+		},
+		gitCommitScopes: [
+			["projects", "项目"],
+			["packages", "包"],
+			["components", "组件"],
+			["hooks", "钩子函数"],
+			["utils", "工具函数"],
+			["types", "TS类型声明"],
+			["styles", "代码风格"],
+			["deps", "项目依赖"],
+			["release", "发布项目新版本"],
+			["other", "其他的变更"]
+		],
+		gitCommitTypes: [
+			["feat", "新功能"],
+			["feat-wip", "开发中的功能，比如某功能的部分代码"],
+			["fix", "修复Bug"],
+			["docs", "只涉及文档更新"],
+			["typo", "代码或文档勘误，比如错误拼写"],
+			["style", "修改代码风格，不影响代码含义的变更"],
+			["refactor", "代码重构，既不修复 bug 也不添加功能的代码变更"],
+			["perf", "可提高性能的代码更改"],
+			["optimize", "优化代码质量的代码更改"],
+			["test", "添加缺失的测试或更正现有测试"],
+			["build", "影响构建系统或外部依赖项的更改"],
+			["ci", "对 CI 配置文件和脚本的更改"],
+			["chore", "没有修改src或测试文件的其他变更"],
+			["revert", "还原先前的提交"]
+		],
+		gitCommitVerify: `${bgRed(" 错误 ")} ${red("git 提交信息必须符合 Conventional Commits 标准!")}\n\n${green("推荐使用命令 `pnpm commit` 生成符合 Conventional Commits 标准的提交信息。\n获取有关 Conventional Commits 的更多信息，请访问此链接: https://conventionalcommits.org")}`
+	}
+};
+
+//#endregion
+//#region src/commands/git-commit.ts
+const { prompt } = enquirer;
+/**
+* 构造 Conventional Commits 的校验正则。
+*
+* 必须锚定首尾并把 type 限定成白名单：不锚定的话任何含有 `xx: yy` 的句子都能蒙混过关，不限白名单的话
+* `banana: 修点东西` 也算合规——那这个校验就等于没有。
+*/
+function createCommitMessageRegExp(types) {
+	const alternatives = types.toSorted((a, b) => b.length - a.length).join("|");
+	return /* @__PURE__ */ new RegExp(`^(?:${alternatives})(?:\\([^()]+\\))?!?: .+$`);
+}
+/**
+* Git commit with Conventional Commits standard
+*
+* @param lang
+*/
+async function gitCommit(lang = "en-us") {
+	const { gitCommitMessages, gitCommitScopes, gitCommitTypes } = locales[lang];
+	const typesChoices = gitCommitTypes.map(([value, msg]) => {
+		return {
+			message: `${`${value}:`.padEnd(12)}${msg}`,
+			name: value
+		};
+	});
+	const scopesChoices = gitCommitScopes.map(([value, msg]) => ({
+		message: `${value.padEnd(30)} (${msg})`,
+		name: value
+	}));
+	const result = await prompt([
+		{
+			choices: typesChoices,
+			message: gitCommitMessages.types,
+			name: "types",
+			type: "select"
+		},
+		{
+			choices: scopesChoices,
+			message: gitCommitMessages.scopes,
+			name: "scopes",
+			type: "select"
+		},
+		{
+			message: gitCommitMessages.description,
+			name: "description",
+			type: "text"
+		}
+	]);
+	const breaking = result.description.startsWith("!") ? "!" : "";
+	const description = result.description.replace(/^!/, "").trim();
+	if (!description) throw new Error(gitCommitMessages.emptyDescription);
+	await execCommand("git", [
+		"commit",
+		"-m",
+		`${result.types}(${result.scopes})${breaking}: ${description}`
+	], { stdio: "inherit" });
+}
+/**
+* 读取本次提交的信息文件。
+*
+* 走 `git rev-parse --git-path` 而不是手工拼 `<toplevel>/.git/COMMIT_EDITMSG`：在 worktree 里 `.git` 是文件不是目录，
+* 手工拼出来的路径根本不存在。
+*/
+async function readCommitMessage() {
+	const gitMsgPath = await execCommand("git", [
+		"rev-parse",
+		"--git-path",
+		"COMMIT_EDITMSG"
+	]);
+	return readFileSync(path.resolve(process.cwd(), gitMsgPath), "utf8").trim();
+}
+/** Git commit message verify */
+async function gitCommitVerify(lang = "en-us", ignores = []) {
+	const commitMsg = await readCommitMessage();
+	if (ignores.some((regExp) => regExp.test(commitMsg))) return;
+	const { gitCommitTypes, gitCommitVerify: errorMsg } = locales[lang];
+	const [subject = ""] = commitMsg.split("\n");
+	if (!createCommitMessageRegExp(gitCommitTypes.map(([value]) => value)).test(subject)) throw new Error(errorMsg);
+}
+
+//#endregion
+//#region src/commands/release.ts
+async function release(execute = "pnpm sa changelog", push = true) {
+	await versionBump({
+		all: true,
+		commit: "chore(projects): release v%s",
+		execute,
+		files: ["**/package.json", "!**/node_modules/**"],
+		push,
+		tag: true
+	});
+}
+
+//#endregion
+//#region src/template/resolve.ts
+const SKIP_DIRS = new Set([
+	".git",
+	".turbo",
+	"dist",
+	"node_modules"
+]);
+/**
+* `@skyroc/tsconfig` 的内容已经被展平进生成应用的 tsconfig.json，再留一条依赖只会指向一个装不上的私有包。
+* 其余 workspace 依赖都必须保留——vite.config、uno.config 真的会 import 它们。
+*/
+const INLINED_DEV_DEPENDENCIES = new Set(["@skyroc/tsconfig"]);
+/**
+* shell 源码会被 `sa create-admin` 原样复制进生成项目的 `src/framework`（经 `@shell` 别名访问），
+* 依赖里不能再指向这个私有 workspace 包。
+*/
+const INLINED_DEPENDENCIES = new Set(["@skyroc/web-admin-shell"]);
+/**
+* 把 pnpm 的依赖协议解析成 registry 能识别的版本区间。
+*
+* `workspace:*` 走 `^version` 而不是 pnpm publish 时的精确版本——脚手架产出的是一个新项目，它应该能跟着上游收补丁。
+*/
+function resolveDependencySpecifier(name, specifier, context) {
+	if (specifier.startsWith("workspace:")) {
+		const range = specifier.slice(10);
+		const workspacePackage = context.workspacePackages.get(name);
+		if (!workspacePackage) throw new Error(`Cannot resolve workspace dependency "${name}": no such package in the workspace.`);
+		if (range === "*") return `^${workspacePackage.version}`;
+		if (range === "^" || range === "~") return `${range}${workspacePackage.version}`;
+		return range;
+	}
+	if (specifier.startsWith("catalog:")) {
+		const catalogName = specifier.slice(8).trim();
+		const catalog = catalogName ? context.catalog.catalogs[catalogName] : context.catalog.defaultCatalog;
+		if (!catalog) throw new Error(`Cannot resolve "${name}": catalog "${catalogName || "default"}" is not defined.`);
+		const version = catalog[name];
+		if (!version) throw new Error(`Cannot resolve "${name}": not listed in catalog "${catalogName || "default"}".`);
+		return version;
+	}
+	return specifier;
+}
+function resolveDependencies(dependencies, context, omit = /* @__PURE__ */ new Set()) {
+	const resolved = {};
+	const unpublished = [];
+	const entries = Object.entries(dependencies ?? {}).filter(([name]) => !omit.has(name));
+	for (const [name, specifier] of entries) {
+		resolved[name] = resolveDependencySpecifier(name, specifier, context);
+		if (specifier.startsWith("workspace:") && context.workspacePackages.get(name)?.isPrivate) unpublished.push(name);
+	}
+	return {
+		resolved,
+		unpublished
+	};
+}
+/** tsconfig 的 extends 是「compilerOptions 浅合并、其余字段子覆盖父」。 */
+function mergeTsconfig(base, child) {
+	const merged = {
+		...base,
+		...child
+	};
+	merged.compilerOptions = {
+		...base.compilerOptions ?? {},
+		...child.compilerOptions ?? {}
+	};
+	delete merged.extends;
+	delete merged.$schema;
+	delete merged.display;
+	return merged;
+}
+/** oxlint 的 extends 是「rules 浅合并、overrides 按父→子拼接、其余字段子覆盖父」。 */
+function mergeOxlintConfig(base, child) {
+	const merged = {
+		...base,
+		...child
+	};
+	merged.rules = {
+		...base.rules ?? {},
+		...child.rules ?? {}
+	};
+	const baseOverrides = base.overrides ?? [];
+	const childOverrides = child.overrides ?? [];
+	if (baseOverrides.length > 0 || childOverrides.length > 0) merged.overrides = [...baseOverrides, ...childOverrides];
+	delete merged.extends;
+	delete merged.$schema;
+	return merged;
+}
+async function readJsonFile(filePath) {
+	const withoutComments = (await readFile(filePath, "utf8")).replaceAll(/^\s*\/\/.*$/gm, "").replaceAll(/,(\s*[\]}])/g, "$1");
+	return JSON.parse(withoutComments);
+}
+function resolveExtendsPath(specifier, fromDir) {
+	if (specifier.startsWith(".")) return path.resolve(fromDir, specifier);
+	return createRequire(path.join(fromDir, "package.json")).resolve(specifier);
+}
+/** 沿 extends 链自底向上展平一份 JSON 配置。 */
+async function flattenJsonConfig(filePath, merge) {
+	const config = await readJsonFile(filePath);
+	const extendsField = config.extends;
+	const parents = Array.isArray(extendsField) ? extendsField : [extendsField].filter(Boolean);
+	let merged = {};
+	for (const parent of parents) {
+		const parentConfig = await flattenJsonConfig(resolveExtendsPath(parent, path.dirname(filePath)), merge);
+		merged = merge(merged, parentConfig);
+	}
+	return merge(merged, config);
+}
+function segmentToRegExp(segment) {
+	const source = segment.split("*").map((part) => part.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)).join("[^/]*");
+	return /* @__PURE__ */ new RegExp(`^${source}$`);
+}
+/** 逐段匹配 pnpm-workspace.yaml 的 packages glob，支持 `*` 与 `**`。 */
+function matchesWorkspacePattern(relativePath, pattern) {
+	const pathSegments = relativePath.split("/");
+	const patternSegments = pattern.split("/");
+	function match(pathIndex, patternIndex) {
+		if (patternIndex === patternSegments.length) return pathIndex === pathSegments.length;
+		const patternSegment = patternSegments[patternIndex];
+		if (patternSegment === "**") {
+			for (let skip = pathIndex; skip <= pathSegments.length; skip += 1) if (match(skip, patternIndex + 1)) return true;
+			return false;
+		}
+		if (pathIndex === pathSegments.length) return false;
+		return segmentToRegExp(patternSegment).test(pathSegments[pathIndex]) && match(pathIndex + 1, patternIndex + 1);
+	}
+	return match(0, 0);
+}
+async function readWorkspaceCatalog(workspaceRoot) {
+	const workspaceFile = parseYAML(await readFile(path.join(workspaceRoot, "pnpm-workspace.yaml"), "utf8"));
+	return {
+		catalogs: workspaceFile.catalogs ?? {},
+		defaultCatalog: workspaceFile.catalog ?? {},
+		overrides: workspaceFile.overrides ?? {},
+		packages: workspaceFile.packages ?? []
+	};
+}
+async function collectWorkspacePackages(workspaceRoot, patterns) {
+	const isWorkspaceDir = (relativePath) => patterns.some((pattern) => matchesWorkspacePattern(relativePath, pattern));
+	const maxDepth = Math.max(...patterns.map((pattern) => pattern.split("/").length), 1);
+	const packages = /* @__PURE__ */ new Map();
+	async function walk(currentDir, depth) {
+		const directories = (await readdir(currentDir, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !SKIP_DIRS.has(entry.name));
+		await Promise.all(directories.map(async (entry) => {
+			const fullPath = path.join(currentDir, entry.name);
+			if (isWorkspaceDir(path.relative(workspaceRoot, fullPath).split(path.sep).join("/"))) {
+				const packageJsonPath = path.join(fullPath, "package.json");
+				if (existsSync(packageJsonPath)) {
+					const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+					if (packageJson.name) packages.set(packageJson.name, {
+						isPrivate: Boolean(packageJson.private),
+						version: packageJson.version ?? "0.0.0"
+					});
+				}
+			}
+			if (depth < maxDepth) await walk(fullPath, depth + 1);
+		}));
+	}
+	await walk(workspaceRoot, 1);
+	return packages;
+}
+/** 在 monorepo 内解析出模板的全部物化数据。只能在仓库内调用。 */
+async function resolveTemplateMeta(options) {
+	const { sourceDir, workspaceRoot } = options;
+	const catalog = await readWorkspaceCatalog(workspaceRoot);
+	const context = {
+		catalog,
+		workspacePackages: await collectWorkspacePackages(workspaceRoot, catalog.packages)
+	};
+	const packageJson = JSON.parse(await readFile(path.join(sourceDir, "package.json"), "utf8"));
+	const dependencies = resolveDependencies(packageJson.dependencies, context, INLINED_DEPENDENCIES);
+	const devDependencies = resolveDependencies(packageJson.devDependencies, context, INLINED_DEV_DEPENDENCIES);
+	const [tsconfig, oxlintConfig] = await Promise.all([flattenJsonConfig(path.join(sourceDir, "tsconfig.json"), mergeTsconfig), flattenJsonConfig(path.join(sourceDir, ".oxlintrc.json"), mergeOxlintConfig)]);
+	return {
+		dependencies: dependencies.resolved,
+		devDependencies: devDependencies.resolved,
+		oxlintConfig,
+		overrides: catalog.overrides,
+		tsconfig,
+		unpublishedPackages: Array.from(new Set([...dependencies.unpublished, ...devDependencies.unpublished]))
+	};
+}
+
+//#endregion
+//#region src/commands/sync-admin-template.ts
+const TEMPLATE_NAME = "admin";
+/** shell 源码模板目录名，与 templates/admin 平级，保持 admin/ 仍是 apps/admin 的逐字节镜像。 */
+const SHELL_TEMPLATE_NAME = "admin-shell";
+/** shell 里会被复制进生成项目 src/framework 的运行时目录；配置、测试与文档不属于产物。 */
+const SHELL_RUNTIME_DIRS = [
+	"i18n",
+	"layouts",
+	"notification",
+	"runtime",
+	"styles",
+	"theme",
+	"types",
+	"ui"
+];
+const MAX_REPORTED_DIFFERENCES = 20;
+/** 构建产物与工具缓存目录，同步时既不复制也不参与比对。 */
+const TECHNICAL_DIRS = new Set([
+	".tanstack",
+	".turbo",
+	"coverage",
+	"dist",
+	"node_modules"
+]);
+function normalizeRelativePath(filePath) {
+	return filePath.split(path.sep).join("/");
+}
+function isLocalEnvFile(relativePath) {
+	const basename = path.posix.basename(relativePath);
+	return basename === ".env.local" || /^\.env\..*\.local$/.test(basename);
+}
+function isTechnicalGeneratedPath(relativePath) {
+	if (!relativePath) return false;
+	const segments = relativePath.split("/");
+	const basename = segments.at(-1);
+	return basename === ".DS_Store" || basename?.endsWith(".tsbuildinfo") || basename?.endsWith(".log") || isLocalEnvFile(relativePath) || segments.some((segment) => TECHNICAL_DIRS.has(segment));
+}
+function isRouteTreeFile(relativePath) {
+	return relativePath === "src/features/router/routeTree.gen.ts";
+}
+function shouldCopyPath(relativePath) {
+	return !isTechnicalGeneratedPath(relativePath) && !isRouteTreeFile(relativePath);
+}
+function shouldComparePath(relativePath) {
+	return !isTechnicalGeneratedPath(relativePath);
+}
+function resolveSourceDir(workspaceRoot, source) {
+	return path.resolve(workspaceRoot, source || "apps/admin");
+}
+function resolveTargetDir(target) {
+	return path.resolve(process.cwd(), target || path.join(getPackageRoot(), "templates", TEMPLATE_NAME));
+}
+async function copyAdminSource(sourceDir, targetDir) {
+	await rm(targetDir, {
+		force: true,
+		recursive: true
+	});
+	await cp(sourceDir, targetDir, {
+		filter: (source) => {
+			return shouldCopyPath(normalizeRelativePath(path.relative(sourceDir, source)));
+		},
+		recursive: true
+	});
+}
+async function copyShellSource(shellSourceDir, shellTargetDir) {
+	await rm(shellTargetDir, {
+		force: true,
+		recursive: true
+	});
+	for (const dir of SHELL_RUNTIME_DIRS) {
+		const from = path.join(shellSourceDir, dir);
+		if (!existsSync(from)) throw new Error(`Admin shell source dir is missing: ${from}`);
+		await cp(from, path.join(shellTargetDir, dir), {
+			filter: (source) => !source.split(path.sep).some((segment) => TECHNICAL_DIRS.has(segment)),
+			recursive: true
+		});
+	}
+}
+async function generateRouteTree(targetDir) {
+	const { configSchema, Generator } = await import("@tanstack/router-generator").catch(() => {
+		throw new Error("@tanstack/router-generator is not installed. sync-admin-template only runs inside the skyroc-admin monorepo.");
+	});
+	const routeTreeTmpDir = await mkdtemp(path.join(tmpdir(), "skyroc-route-tree-"));
+	try {
+		await new Generator({
+			config: configSchema.parse({
+				autoCodeSplitting: true,
+				disableLogging: true,
+				generatedRouteTree: path.join(targetDir, "src/features/router/routeTree.gen.ts"),
+				routeFileIgnorePattern: "(?:^|/)(components|modules)(?:/|$)|(?:^|/)(loading|error|not-found)(?:.tsx?|$)",
+				routesDirectory: path.join(targetDir, "src/pages"),
+				routeToken: "layout",
+				target: "react",
+				tmpDir: routeTreeTmpDir
+			}),
+			root: targetDir
+		}).run();
+	} finally {
+		await rm(routeTreeTmpDir, {
+			force: true,
+			recursive: true
+		});
+	}
+}
+async function collectFiles(dir) {
+	const files = [];
+	async function walk(currentDir) {
+		const entries = await readdir(currentDir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = path.join(currentDir, entry.name);
+			const relativePath = normalizeRelativePath(path.relative(dir, fullPath));
+			if (!shouldComparePath(relativePath)) continue;
+			if (entry.isDirectory()) {
+				await walk(fullPath);
+				continue;
+			}
+			if (entry.isFile()) files.push(relativePath);
+		}
+	}
+	if (existsSync(dir)) await walk(dir);
+	return files.toSorted((a, b) => a.localeCompare(b));
+}
+async function compareFiles(leftFile, rightFile) {
+	const [leftStat, rightStat] = await Promise.all([stat(leftFile), stat(rightFile)]);
+	if (leftStat.size !== rightStat.size) return false;
+	const [leftContent, rightContent] = await Promise.all([readFile(leftFile), readFile(rightFile)]);
+	return leftContent.equals(rightContent);
+}
+async function compareDirectories(leftDir, rightDir) {
+	const [leftFiles, rightFiles] = await Promise.all([collectFiles(leftDir), collectFiles(rightDir)]);
+	const leftFileSet = new Set(leftFiles);
+	const rightFileSet = new Set(rightFiles);
+	const allFiles = Array.from(new Set([...leftFiles, ...rightFiles])).toSorted((a, b) => a.localeCompare(b));
+	const differences = [];
+	for (const file of allFiles) {
+		if (!leftFileSet.has(file)) {
+			differences.push({
+				path: file,
+				type: "added"
+			});
+			continue;
+		}
+		if (!rightFileSet.has(file)) {
+			differences.push({
+				path: file,
+				type: "removed"
+			});
+			continue;
+		}
+		if (!await compareFiles(path.join(leftDir, file), path.join(rightDir, file))) differences.push({
+			path: file,
+			type: "changed"
+		});
+	}
+	return differences;
+}
+/**
+* 产出一份完整快照：模板目录 + 物化元数据。
+*
+* 元数据放在模板目录外层，这样 `templates/admin/` 依然是 `apps/admin` 的逐字节镜像，比对逻辑不需要为 sidecar 开特例。
+*/
+async function generateSnapshot(workspaceRoot, sourceDir, targetDir) {
+	if (!existsSync(sourceDir)) throw new Error(`Admin source is missing: ${sourceDir}`);
+	const shellSourceDir = path.join(workspaceRoot, "packages/web/admin");
+	const shellTargetDir = path.join(path.dirname(targetDir), SHELL_TEMPLATE_NAME);
+	await copyAdminSource(sourceDir, targetDir);
+	await copyShellSource(shellSourceDir, shellTargetDir);
+	await generateRouteTree(targetDir);
+	const meta = await resolveTemplateMeta({
+		sourceDir,
+		workspaceRoot
+	});
+	const metaContent = stringifyTemplateMeta(meta);
+	await writeFile(path.join(path.dirname(targetDir), TEMPLATE_META_FILE), metaContent);
+	return {
+		meta,
+		metaContent
+	};
+}
+function formatDifferences(differences) {
+	const detail = differences.slice(0, MAX_REPORTED_DIFFERENCES).map((item) => `  ${item.type.padEnd(7)} ${item.path}`).join("\n");
+	if (differences.length <= MAX_REPORTED_DIFFERENCES) return detail;
+	return `${detail}\n  ...and ${differences.length - MAX_REPORTED_DIFFERENCES} more`;
+}
+async function readMetaContent(metaPath) {
+	if (!existsSync(metaPath)) return "";
+	return readFile(metaPath, "utf8");
+}
+async function checkAdminTemplate(workspaceRoot, sourceDir, targetDir) {
+	const tempDir = await mkdtemp(path.join(tmpdir(), "skyroc-admin-template-"));
+	const generatedDir = path.join(tempDir, TEMPLATE_NAME);
+	try {
+		const { metaContent } = await generateSnapshot(workspaceRoot, sourceDir, generatedDir);
+		const differences = await compareDirectories(targetDir, generatedDir);
+		const shellDifferences = await compareDirectories(path.join(path.dirname(targetDir), SHELL_TEMPLATE_NAME), path.join(tempDir, SHELL_TEMPLATE_NAME));
+		differences.push(...shellDifferences.map((item) => ({
+			...item,
+			path: `${SHELL_TEMPLATE_NAME}/${item.path}`
+		})));
+		const currentMetaContent = await readMetaContent(path.join(path.dirname(targetDir), TEMPLATE_META_FILE));
+		if (currentMetaContent !== metaContent) differences.push({
+			path: TEMPLATE_META_FILE,
+			type: currentMetaContent ? "changed" : "added"
+		});
+		if (differences.length > 0) throw new Error([
+			red("Admin template is out of date."),
+			`${cyan("source")} ${sourceDir}`,
+			`${cyan("target")} ${targetDir}`,
+			yellow("Run pnpm sa sync-admin-template to regenerate it."),
+			formatDifferences(differences)
+		].join("\n"));
+		console.log(green("Admin template is up to date."));
+	} finally {
+		await rm(tempDir, {
+			force: true,
+			recursive: true
+		});
+	}
+}
+async function syncAdminTemplate(options = {}) {
+	const workspaceRoot = getWorkspaceRoot();
+	const sourceDir = resolveSourceDir(workspaceRoot, options.source);
+	const targetDir = resolveTargetDir(options.target);
+	if (options.check) {
+		await checkAdminTemplate(workspaceRoot, sourceDir, targetDir);
+		return;
+	}
+	const { meta } = await generateSnapshot(workspaceRoot, sourceDir, targetDir);
+	console.log(green("Synced admin template."));
+	console.log(`${cyan("source")} ${sourceDir}`);
+	console.log(`${cyan("target")} ${targetDir}`);
+	console.log(`${cyan("meta")}   ${path.join(path.dirname(targetDir), TEMPLATE_META_FILE)}`);
+	if (meta.unpublishedPackages.length > 0) console.log(yellow(`warning  standalone apps will not install these private workspace packages: ${meta.unpublishedPackages.join(", ")}`));
+}
+
+//#endregion
+//#region src/commands/update-pkg.ts
+async function updatePkg(args = ["--deep", "-u"]) {
+	await execCommand("npx", ["npm-check-updates", ...args], { stdio: "inherit" });
+}
+
+//#endregion
+//#region src/config/index.ts
+const defaultOptions = {
+	cwd: process.cwd(),
+	cleanupDirs: [
+		"**/dist",
+		"**/package-lock.json",
+		"**/yarn.lock",
+		"**/pnpm-lock.yaml",
+		"**/node_modules"
+	],
+	ncuCommandArgs: ["--deep", "-u"],
+	changelogOptions: {},
+	gitCommitVerifyIgnores: [
+		/^((Merge pull request)|(Merge (.*?) into (.*?)|(Merge branch (.*?)))(?:\r?\n)*$)/m,
+		/^(Merge tag (.*?))(?:\r?\n)*$/m,
+		/^(R|r)evert (.*)/,
+		/^(amend|fixup|squash)!/,
+		/^(Merged (.*?)(in|into) (.*)|Merged PR (.*): (.*))/,
+		/^Merge remote-tracking branch(\s*)(.*)/,
+		/^Automatic merge(.*)/,
+		/^Auto-merged (.*?) into (.*)/
+	]
+};
+/**
+* 加载 CLI 配置。
+*
+* 先读历史遗留的 `soybean.*`，再让 `skyroc.*` 覆盖在上面——包名早已改成 `@skyroc/scripts`，但旧配置文件不该一升级就失效。
+*/
+async function loadCliOptions(overrides, cwd = process.cwd()) {
+	const { config: legacyConfig } = await loadConfig({
+		name: "soybean",
+		defaults: defaultOptions,
+		cwd,
+		packageJson: true
+	});
+	const { config } = await loadConfig({
+		name: "skyroc",
+		defaults: legacyConfig,
+		overrides,
+		cwd,
+		packageJson: true
+	});
+	return config;
+}
+
+//#endregion
+export { createCommitMessageRegExp as a, locales as c, replaceEnvValue as d, toStoragePrefix as f, genChangelog as h, release as i, createAdminTemplate as l, cleanup as m, updatePkg as n, gitCommit as o, toTitle as p, syncAdminTemplate as r, gitCommitVerify as s, loadCliOptions as t, normalizePackageName as u };