@modern-js/create 3.7.0 → 3.8.1

package/dist/index.js

@@ -12,7 +12,8 @@ class I18CLILanguageDetector {
         return LC;
     }
     detect() {
-        const shellLocale = process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? process.env.LANGUAGE ?? Intl.DateTimeFormat().resolvedOptions().locale;
+        const env = globalThis.process?.env;
+        const shellLocale = env?.LC_ALL ?? env?.LC_MESSAGES ?? env?.LANG ?? env?.LANGUAGE ?? Intl.DateTimeFormat().resolvedOptions().locale;
         return this.formatShellLocale(shellLocale);
     }
 }
@@ -20,6 +21,126 @@ function getLocaleLanguage() {
     const detector = new I18CLILanguageDetector();
     return detector.detect();
 }
+const CLAUDE_IMPORT = '@AGENTS.md';
+const markers = (name)=>({
+        begin: `<!-- BEGIN:${name} -->`,
+        end: `<!-- END:${name} -->`
+    });
+function applyAgentsMd(targetDir, block, markerName) {
+    const { begin, end } = markers(markerName);
+    const file = node_path.join(targetDir, 'AGENTS.md');
+    if (!node_fs.existsSync(file)) {
+        node_fs.writeFileSync(file, `${block}\n`, 'utf-8');
+        return 'created';
+    }
+    const content = node_fs.readFileSync(file, 'utf-8');
+    const from = content.indexOf(begin);
+    const to = content.indexOf(end);
+    if (-1 !== from && -1 !== to && to > from) {
+        const next = content.slice(0, from) + block + content.slice(to + end.length);
+        if (next === content) return 'unchanged';
+        node_fs.writeFileSync(file, next, 'utf-8');
+        return 'updated';
+    }
+    const rest = content.replace(/^\s*/, '');
+    node_fs.writeFileSync(file, rest ? `${block}\n\n${rest}` : `${block}\n`, 'utf-8');
+    return 'added';
+}
+function applyClaudeMd(targetDir) {
+    const file = node_path.join(targetDir, 'CLAUDE.md');
+    if (!node_fs.existsSync(file)) {
+        node_fs.writeFileSync(file, `${CLAUDE_IMPORT}\n`, 'utf-8');
+        return 'created';
+    }
+    const content = node_fs.readFileSync(file, 'utf-8');
+    if (content.split('\n').some((line)=>line.trim() === CLAUDE_IMPORT)) return 'unchanged';
+    node_fs.writeFileSync(file, `${CLAUDE_IMPORT}\n\n${content.replace(/^\s*/, '')}`, 'utf-8');
+    return 'linked';
+}
+function applyAgentFiles(options) {
+    const { targetDir, block, markerName } = options;
+    if (!node_fs.existsSync(targetDir)) throw new Error(`target directory does not exist: ${targetDir}`);
+    return {
+        agents: applyAgentsMd(targetDir, block, markerName),
+        claude: applyClaudeMd(targetDir)
+    };
+}
+const PKG = '@modern-js/app-tools';
+const DOCS_PATH = 'node_modules/@modern-js/app-tools/docs/';
+const BUNDLED_SINCE = '3.8.0';
+function resolveVersion(cwd) {
+    const installed = node_path.join(cwd, 'node_modules', PKG, 'package.json');
+    if (node_fs.existsSync(installed)) try {
+        const { version } = JSON.parse(node_fs.readFileSync(installed, 'utf-8'));
+        if ('string' == typeof version) return version;
+    } catch  {}
+    try {
+        const pkg = JSON.parse(node_fs.readFileSync(node_path.join(cwd, 'package.json'), 'utf-8'));
+        const deps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies
+        };
+        return deps[PKG] ?? null;
+    } catch  {
+        return null;
+    }
+}
+function parseSemver(version) {
+    const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
+    return match ? [
+        Number(match[1]),
+        Number(match[2]),
+        Number(match[3])
+    ] : null;
+}
+function isAtLeast(version, min) {
+    const floor = parseSemver(min);
+    if (!floor) return false;
+    for(let i = 0; i < 3; i++)if (version[i] !== floor[i]) return version[i] > floor[i];
+    return true;
+}
+function supportsBundledDocs(version) {
+    if (!version) return false;
+    if (/^workspace:|-canary[.-]|-alpha[.-]|-beta[.-]/.test(version)) return true;
+    const semver = parseSemver(version);
+    return semver ? isAtLeast(semver, BUNDLED_SINCE) : false;
+}
+function isModernProject(cwd) {
+    try {
+        const pkg = JSON.parse(node_fs.readFileSync(node_path.join(cwd, 'package.json'), 'utf-8'));
+        const deps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies
+        };
+        return Object.keys(deps).some((name)=>name.startsWith('@modern-js/'));
+    } catch  {
+        return false;
+    }
+}
+function buildBlock(markerName) {
+    return [
+        `<!-- BEGIN:${markerName} -->`,
+        '',
+        '# Modern.js: read the docs before you code',
+        '',
+        `> Documentation: **\`${DOCS_PATH}\`**`,
+        `> Index: \`${DOCS_PATH}llms.txt\` — start here when unsure which page to open`,
+        '',
+        'These docs ship inside the package, so they match the Modern.js',
+        'version this project installed exactly. Your training data is likely',
+        'outdated — **treat them as the source of truth**, and do not answer',
+        'from memory on Modern.js configuration, APIs or directory conventions.',
+        '',
+        '**🟢 Read the docs before you touch anything, except for:**',
+        '',
+        '- Writing ordinary React components (not route components)',
+        '- Editing CSS or style files',
+        '- Adding utility functions or business logic',
+        '- Installing ordinary npm packages (unrelated to Modern.js)',
+        '',
+        `<!-- END:${markerName} -->`
+    ].join('\n');
+}
 var isArray = Array.isArray;
 const lodash_es_isArray = isArray;
 var freeGlobal = 'object' == typeof global && global && global.Object === Object && global;
@@ -442,16 +563,29 @@ const EN_LOCALE = {
     error: {
         projectNameEmpty: 'Error: Project name cannot be empty',
         directoryExists: 'Error: Directory "{projectName}" already exists and is not empty',
-        createFailed: 'Error creating project:'
+        createFailed: 'Error creating project:',
+        agentsMdOnlyConflict: 'Error: --agents-md-only only updates the current project and cannot be combined with a project name or --no-agents-md'
     },
     message: {
         welcome: '🚀 Welcome to Modern.js',
         success: '✨ Created successfully!',
+        agentsMd: '✔ AGENTS.md & CLAUDE.md generated — AI coding agents will pick them up automatically. (--no-agents-md to skip)',
         nextSteps: '📋 Next steps:',
         step1: 'cd {projectName}',
         step2: 'pnpm install',
         step3: 'pnpm dev'
     },
+    agentsCmd: {
+        created: '✔ Created {file}',
+        updatedBlock: '✔ Updated the modernjs-agent-rules block in {file}',
+        addedBlock: '✔ Added the modernjs-agent-rules block to the top of {file}',
+        linked: '✔ Added the `@AGENTS.md` import to {file}',
+        unchanged: '• {file} is already up to date',
+        done: '✨ Done — AI coding agents will read {location}.',
+        targetNotFound: 'Error: target directory "{dir}" does not exist',
+        notAProject: 'Error: not a Modern.js project — run this in a project root',
+        unsupportedVersion: '• @modern-js/app-tools@{version} does not ship bundled docs; nothing was changed. Add https://modernjs.dev/llms.txt to AGENTS.md so AI tools can reach the framework docs, or upgrade to {since} or later and re-run this command'
+    },
     help: {
         title: '🚀 Modern.js Project Creator',
         description: 'Create a new Modern.js project with ease',
@@ -462,11 +596,13 @@ const EN_LOCALE = {
         optionVersion: '  -v, --version  Display version information',
         optionLang: '  -l, --lang     Set the language (zh or en)',
         optionSub: '  -s, --sub       Mark as a subproject (package in monorepo)',
+        optionNoAgentsMd: '  --no-agents-md  Skip generating AGENTS.md / CLAUDE.md for AI coding agents',
+        optionAgentsMdOnly: '  --agents-md-only  Only add/refresh AGENTS.md / CLAUDE.md in the current project (no scaffolding)',
         examples: '💡 Examples:',
         example1: '  create my-app',
         example2: '  create my-app --lang zh',
         example3: '  create my-app --sub',
-        example4: '  create --help',
+        example4: '  create --agents-md-only   (add/refresh AGENTS.md & CLAUDE.md in an existing project)',
         moreInfo: '📚 Learn more: https://modernjs.dev'
     },
     version: {
@@ -480,16 +616,29 @@ const ZH_LOCALE = {
     error: {
         projectNameEmpty: '错误: 项目名称不能为空',
         directoryExists: '错误: 目录 "{projectName}" 已存在且不为空',
-        createFailed: '创建项目时出错:'
+        createFailed: '创建项目时出错:',
+        agentsMdOnlyConflict: '错误: --agents-md-only 只更新当前项目，不能与项目名或 --no-agents-md 同时使用'
     },
     message: {
         welcome: '🚀 欢迎使用 Modern.js',
         success: '✨ 创建成功！',
+        agentsMd: '✔ 已生成 AGENTS.md 和 CLAUDE.md —— AI 编码助手会自动读取。（--no-agents-md 可跳过）',
         nextSteps: '📋 下一步：',
         step1: 'cd {projectName}',
         step2: 'pnpm install',
         step3: 'pnpm dev'
     },
+    agentsCmd: {
+        created: '✔ 已创建 {file}',
+        updatedBlock: '✔ 已更新 {file} 中的 modernjs-agent-rules 块',
+        addedBlock: '✔ 已在 {file} 顶部添加 modernjs-agent-rules 块',
+        linked: '✔ 已向 {file} 添加 `@AGENTS.md` 引用',
+        unchanged: '• {file} 已是最新',
+        done: '✨ 完成 —— AI 编码助手会读取 {location}。',
+        targetNotFound: '错误: 目标目录 "{dir}" 不存在',
+        notAProject: '错误: 当前目录不是 Modern.js 项目，请在项目根目录运行',
+        unsupportedVersion: '• 当前 @modern-js/app-tools@{version} 不支持随包文档，未修改任何文件。可在 AGENTS.md 中补充 https://modernjs.dev/llms.txt 供 AI 工具获取框架知识，或升级到 {since} 及以上后重新执行本命令'
+    },
     help: {
         title: '🚀 Modern.js 项目创建工具',
         description: '快速创建一个新的 Modern.js 项目',
@@ -500,11 +649,13 @@ const ZH_LOCALE = {
         optionVersion: '  -v, --version  显示版本信息',
         optionLang: '  -l, --lang     设置语言 (zh 或 en)',
         optionSub: '  -s, --sub       标记为子项目（monorepo 中的子包）',
+        optionNoAgentsMd: '  --no-agents-md  跳过生成 AGENTS.md / CLAUDE.md（AI 编码助手指引文件）',
+        optionAgentsMdOnly: '  --agents-md-only  仅为当前项目补齐/更新 AGENTS.md / CLAUDE.md（不创建项目）',
         examples: '💡 示例:',
         example1: '  create my-app',
         example2: '  create my-app --lang zh',
         example3: '  create my-app --sub',
-        example4: '  create --help',
+        example4: '  create --agents-md-only   (为已有项目补齐/更新 AGENTS.md 和 CLAUDE.md)',
         moreInfo: '📚 更多信息: https://modernjs.dev'
     },
     version: {
@@ -516,6 +667,51 @@ const localeKeys = i18n.init('en', {
     zh: ZH_LOCALE,
     en: EN_LOCALE
 });
+const MARKER_NAME = 'modernjs-agent-rules';
+const AGENTS_MESSAGES = {
+    created: localeKeys.agentsCmd.created,
+    updated: localeKeys.agentsCmd.updatedBlock,
+    added: localeKeys.agentsCmd.addedBlock,
+    unchanged: localeKeys.agentsCmd.unchanged
+};
+const CLAUDE_MESSAGES = {
+    created: localeKeys.agentsCmd.created,
+    linked: localeKeys.agentsCmd.linked,
+    unchanged: localeKeys.agentsCmd.unchanged
+};
+function runAgentsMd(_templateDir, targetDir) {
+    if (!node_fs.existsSync(targetDir)) {
+        console.error(i18n.t(localeKeys.agentsCmd.targetNotFound, {
+            dir: targetDir
+        }));
+        process.exit(1);
+    }
+    if (!isModernProject(targetDir)) {
+        console.error(i18n.t(localeKeys.agentsCmd.notAProject));
+        process.exit(1);
+    }
+    const version = resolveVersion(targetDir);
+    if (!supportsBundledDocs(version)) return void console.log(i18n.t(localeKeys.agentsCmd.unsupportedVersion, {
+        version: version ?? 'unknown',
+        since: "3.8.0"
+    }));
+    const block = buildBlock(MARKER_NAME);
+    const result = applyAgentFiles({
+        targetDir,
+        block,
+        markerName: MARKER_NAME
+    });
+    console.log(i18n.t(AGENTS_MESSAGES[result.agents], {
+        file: 'AGENTS.md'
+    }));
+    console.log(i18n.t(CLAUDE_MESSAGES[result.claude], {
+        file: 'CLAUDE.md'
+    }));
+    console.log('');
+    console.log(i18n.t(localeKeys.agentsCmd.done, {
+        location: DOCS_PATH
+    }));
+}
 const src_dirname = node_path.dirname(fileURLToPath(import.meta.url));
 const templateDir = node_path.resolve(src_dirname, '..', 'template');
 const detectLanguage = ()=>{
@@ -567,6 +763,8 @@ function showHelp() {
     console.log(i18n.t(localeKeys.help.optionVersion));
     console.log(i18n.t(localeKeys.help.optionLang));
     console.log(i18n.t(localeKeys.help.optionSub));
+    console.log(i18n.t(localeKeys.help.optionNoAgentsMd));
+    console.log(i18n.t(localeKeys.help.optionAgentsMdOnly));
     console.log('');
     console.log(i18n.t(localeKeys.help.examples));
     console.log(i18n.t(localeKeys.help.example1));
@@ -590,12 +788,30 @@ function promptInput(question) {
         });
     });
 }
+const VALUE_FLAGS = [
+    '--lang',
+    '-l'
+];
+const BOOLEAN_FLAGS = [
+    '--help',
+    '-h',
+    '--version',
+    '-v',
+    '--sub',
+    '-s',
+    '--no-sub',
+    '--no-agents-md',
+    '--agents-md-only'
+];
 function detectSubprojectFlag() {
     const args = process.argv.slice(2);
     if (args.includes('--sub') || args.includes('-s')) return true;
     if (args.includes('--no-sub')) return false;
     return null;
 }
+function detectNoAgentsMdFlag() {
+    return process.argv.slice(2).includes('--no-agents-md');
+}
 function isDirectoryEmpty(dirPath) {
     if (!node_fs.existsSync(dirPath)) return false;
     try {
@@ -607,7 +823,7 @@ function isDirectoryEmpty(dirPath) {
 }
 async function getProjectName() {
     const args = process.argv.slice(2);
-    const projectNameArg = args.find((arg, index)=>'--lang' !== arg && '-l' !== arg && '--help' !== arg && '-h' !== arg && '--version' !== arg && '-v' !== arg && '--sub' !== arg && '-s' !== arg && '--no-sub' !== arg && (0 === index || '--lang' !== args[index - 1] && '-l' !== args[index - 1] && '--help' !== args[index - 1] && '-h' !== args[index - 1] && '--version' !== args[index - 1] && '-v' !== args[index - 1] && '--sub' !== args[index - 1] && '-s' !== args[index - 1] && '--no-sub' !== args[index - 1]));
+    const projectNameArg = args.find((arg, index)=>!VALUE_FLAGS.includes(arg) && !BOOLEAN_FLAGS.includes(arg) && !(index > 0 && VALUE_FLAGS.includes(args[index - 1])));
     if (projectNameArg) return {
         name: projectNameArg,
         useCurrentDir: false
@@ -631,6 +847,15 @@ async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || args.includes('-h')) return void showHelp();
     if (args.includes('--version') || args.includes('-v')) return void showVersion();
+    if (args.includes('--agents-md-only')) {
+        const hasProjectName = args.some((arg, index)=>!arg.startsWith('-') && !VALUE_FLAGS.includes(args[index - 1]));
+        if (hasProjectName || args.includes('--no-agents-md')) {
+            console.error(i18n.t(localeKeys.error.agentsMdOnlyConflict));
+            process.exit(1);
+        }
+        runAgentsMd(templateDir, process.cwd());
+        return;
+    }
     console.log(`\n${i18n.t(localeKeys.message.welcome)}\n`);
     const { name: projectName, useCurrentDir } = await getProjectName();
     const targetDir = useCurrentDir ? process.cwd() : node_path.isAbsolute(projectName) ? projectName : node_path.resolve(process.cwd(), projectName);
@@ -648,10 +873,12 @@ async function main() {
     const version = createPackage.version || 'latest';
     const subprojectFlag = detectSubprojectFlag();
     const isSubproject = true === subprojectFlag;
+    const noAgentsMd = detectNoAgentsMdFlag();
     copyTemplate(templateDir, targetDir, {
         packageName: projectName,
         version,
-        isSubproject
+        isSubproject,
+        noAgentsMd
     });
     const targetPackageJson = node_path.join(targetDir, 'package.json');
     const packageJson = JSON.parse(node_fs.readFileSync(targetPackageJson, 'utf-8'));
@@ -673,6 +900,7 @@ async function main() {
     const dim = '\x1b[2m\x1b[3m';
     const reset = '\x1b[0m';
     console.log(`${i18n.t(localeKeys.message.success)}\n`);
+    if (!noAgentsMd && !isSubproject) console.log(`${i18n.t(localeKeys.message.agentsMd)}\n`);
     console.log(i18n.t(localeKeys.message.nextSteps));
     if (!useCurrentDir) console.log(`${dim}   ${i18n.t(localeKeys.message.step1, {
         projectName
@@ -688,7 +916,13 @@ function copyTemplate(src, dest, options) {
         '.gitignore.handlebars',
         'biome.json',
         '.npmrc',
-        '.nvmrc'
+        '.nvmrc',
+        'AGENTS.md',
+        'CLAUDE.md'
+    ];
+    const agentFiles = [
+        'AGENTS.md',
+        'CLAUDE.md'
     ];
     function copyRecursive(srcDir, destDir) {
         const entries = node_fs.readdirSync(srcDir, {
@@ -696,6 +930,7 @@ function copyTemplate(src, dest, options) {
         });
         for (const entry of entries){
             if (options.isSubproject && excludeInSubproject.includes(entry.name)) continue;
+            if (options.noAgentsMd && agentFiles.includes(entry.name)) continue;
             const srcPath = node_path.join(srcDir, entry.name);
             let destPath = node_path.join(destDir, entry.name);
             if (entry.isDirectory()) {

package/package.json

@@ -19,7 +19,7 @@
   "engines": {
     "node": ">=20"
   },
-  "version": "3.7.0",
+  "version": "3.8.1",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/index.js",
   "bin": {
@@ -38,7 +38,8 @@
     "@types/node": "^20",
     "tsx": "^4.22.4",
     "typescript": "^5",
-    "@modern-js/i18n-utils": "3.7.0",
+    "@modern-js/i18n-utils": "3.8.1",
+    "@scripts/rstest-config": "2.66.0",
     "@modern-js/rslib": "2.68.10"
   },
   "publishConfig": {
@@ -48,6 +49,7 @@
   "scripts": {
     "build": "rslib build",
     "dev": "rslib build -w",
-    "start": "node ./dist/index.js"
+    "start": "node ./dist/index.js",
+    "test": "rstest"
   }
 }

package/template/AGENTS.md

@@ -0,0 +1,20 @@
+<!-- BEGIN:modernjs-agent-rules -->
+
+# Modern.js: read the docs before you code
+
+> Documentation: **`node_modules/@modern-js/app-tools/docs/`**
+> Index: `node_modules/@modern-js/app-tools/docs/llms.txt` — start here when unsure which page to open
+
+These docs ship inside the package, so they match the Modern.js
+version this project installed exactly. Your training data is likely
+outdated — **treat them as the source of truth**, and do not answer
+from memory on Modern.js configuration, APIs or directory conventions.
+
+**🟢 Read the docs before you touch anything, except for:**
+
+- Writing ordinary React components (not route components)
+- Editing CSS or style files
+- Adding utility functions or business logic
+- Installing ordinary npm packages (unrelated to Modern.js)
+
+<!-- END:modernjs-agent-rules -->

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md