@migor/cli 0.0.2 → 0.2.0

package/dist/add.js

@@ -0,0 +1,60 @@
+/** add 命令：npm install 第三方单元包并登记进 units.ts 注册表 */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { registerPackage } from './registry.js';
+/** 从 add 参数解析真实包名：支持 name[@version]、@scope/name[@version]、本地路径（file:） */
+function resolvePackageName(arg) {
+    if (arg.startsWith('.') || arg.startsWith('/')) {
+        const pkgFile = join(resolve(arg), 'package.json');
+        if (!existsSync(pkgFile)) {
+            throw new Error(`本地包 ${arg} 缺少 package.json`);
+        }
+        const name = JSON.parse(readFileSync(pkgFile, 'utf8')).name;
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new Error(`本地包 ${arg} 的 package.json 缺少 name 字段`);
+        }
+        return name;
+    }
+    // 去掉版本后缀：@scope/name@1.0.0 → @scope/name；name@1.0.0 → name
+    const at = arg.startsWith('@') ? arg.indexOf('@', 1) : arg.indexOf('@');
+    return at > 0 ? arg.slice(0, at) : arg;
+}
+/** 包名 → DI token：去 scope，转 kebab-case（fooBar → foo-bar，foo_bar → foo-bar） */
+export function packageNameToToken(pkgName) {
+    const bare = pkgName.startsWith('@') ? pkgName.slice(pkgName.indexOf('/') + 1) : pkgName;
+    return bare
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .toLowerCase()
+        .replace(/^-+|-+$/g, '');
+}
+export function addPackage(arg) {
+    const cwd = process.cwd();
+    const r = spawnSync('npm', ['install', arg], { cwd, stdio: 'inherit' });
+    if (r.error || r.status !== 0) {
+        console.error(`错误：npm install ${arg} 失败，units.ts 未改动`);
+        process.exitCode = 1;
+        return 1;
+    }
+    let pkgName;
+    try {
+        pkgName = resolvePackageName(arg);
+    }
+    catch (err) {
+        console.error(`错误：${err.message}`);
+        process.exitCode = 1;
+        return 1;
+    }
+    const token = packageNameToToken(pkgName);
+    const result = registerPackage(cwd, token, pkgName);
+    if (result === 'registered') {
+        console.log(`已登记到 units.ts：import ${pkgName} → { provide: '${token}' }`);
+    }
+    else {
+        console.log(`units.ts 中「${token}」已注册，跳过登记`);
+    }
+    console.log('约定提示：第三方单元包应 default export 一个 provider 类（或 Provider 对象）；' +
+        '若该包不符合约定，请手工调整 units.ts 中的 import 与条目');
+    return 0;
+}

package/dist/cli.js

@@ -4,12 +4,18 @@ import { createProject } from './create.js';
 import { generateUnit } from './generate.js';
 import { isUnitType, isValidName, UNIT_TYPES } from './templates.js';
 import { RegistryError } from './registry.js';
+import { devServer } from './dev.js';
+import { doctor } from './doctor.js';
+import { addPackage } from './add.js';
 const USAGE = `agentia —— Agentia 框架命令行工具
 
 用法：
   agentia create <name> [--dir <parent>]   创建项目脚手架（目录 <parent|当前目录>/<name>/）
   agentia g <type> <name>                  在当前目录生成单元（别名：generate）
                                            type: ${UNIT_TYPES.join(' | ')}
+  agentia dev                              启动开发模式（tsx watch src/main.ts，热重载）
+  agentia doctor                           装配体检（未登记/悬空单板/命名规范/重复条目）
+  agentia add <pkg>                        安装第三方单元包并登记到 units.ts
   agentia --help                           显示本帮助
 
 name 规则：小写字母开头的小写 kebab-case（如 hello、doc-reviewer）
@@ -71,6 +77,30 @@ function main(argv) {
             throw err;
         }
     }
+    if (command === 'dev') {
+        if (rest.length > 0)
+            return fail(`未知参数：${rest[0]}`);
+        return devServer();
+    }
+    if (command === 'doctor') {
+        if (rest.length > 0)
+            return fail(`未知参数：${rest[0]}`);
+        return doctor();
+    }
+    if (command === 'add') {
+        const [pkg, ...extra] = rest;
+        if (pkg === undefined || extra.length > 0) {
+            return fail('用法：agentia add <pkg>（npm 包名或本地包路径）');
+        }
+        try {
+            return addPackage(pkg);
+        }
+        catch (err) {
+            if (err instanceof RegistryError)
+                return fail(err.message);
+            throw err;
+        }
+    }
     console.error(`错误：未知命令「${command}」\n`);
     console.error(USAGE);
     process.exitCode = 1;

package/dist/create.js

@@ -1,11 +1,11 @@
 /** create 命令：生成 Agentia 项目脚手架 */
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { mainTs, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, toolIndexTs, emptyRegistryTemplate, } from './templates.js';
 import { registerUnit } from './registry.js';
 function write(dir, rel, content) {
     const file = join(dir, rel);
-    mkdirSync(join(file, '..'), { recursive: true });
+    mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, content, 'utf8');
 }
 export function createProject(name, parent) {

package/dist/dev.js

@@ -0,0 +1,30 @@
+/** dev 命令：在项目根目录启动 tsx watch src/main.ts（热重载开发模式） */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function devServer() {
+    const cwd = process.cwd();
+    const entry = join(cwd, 'src', 'main.ts');
+    if (!existsSync(entry)) {
+        console.error('错误：当前目录下未找到 src/main.ts，请先用 agentia create <name> 创建项目（或 cd 到项目根目录）');
+        process.exitCode = 1;
+        return 1;
+    }
+    const child = spawn('npx', ['tsx', 'watch', 'src/main.ts'], { cwd, stdio: 'inherit' });
+    // 把终端信号转发给子进程（tsx watch 需要收到 SIGINT 才能干净退出）
+    const forward = (sig) => () => {
+        if (!child.killed)
+            child.kill(sig);
+    };
+    process.on('SIGINT', forward('SIGINT'));
+    process.on('SIGTERM', forward('SIGTERM'));
+    child.on('error', (err) => {
+        console.error(`错误：启动 dev 失败：${err.message}`);
+        process.exitCode = 1;
+    });
+    child.on('exit', (code, sig) => {
+        // 子进程退出后同步退出码；被信号杀死视为正常（用户 Ctrl+C）
+        process.exitCode = sig ? 0 : (code ?? 0);
+    });
+    return 0;
+}

package/dist/doctor.js

@@ -0,0 +1,87 @@
+/** doctor 命令：静态体检装配健康度（只读文件系统 + units.ts 文本，不 import 用户代码） */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isValidName } from './templates.js';
+/** 解析 units.ts：imports（标识符 → 来源）+ entries（provide token → useClass 标识符） */
+function parseRegistry(content) {
+    const imports = new Map();
+    for (const m of content.matchAll(/^import\s+(\w+)\s+from\s+'([^']+)'/gm)) {
+        imports.set(m[1], m[2]);
+    }
+    const entries = [];
+    for (const m of content.matchAll(/\{\s*provide:\s*'([^']+)'\s*,\s*useClass:\s*(\w+)/g)) {
+        entries.push({ token: m[1], ident: m[2] });
+    }
+    return { imports, entries };
+}
+export function doctor() {
+    const cwd = process.cwd();
+    const unitsDir = join(cwd, 'units');
+    const registryFile = join(cwd, 'units.ts');
+    const folders = existsSync(unitsDir)
+        ? readdirSync(unitsDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+        : [];
+    const content = existsSync(registryFile) ? readFileSync(registryFile, 'utf8') : '';
+    const { imports, entries } = parseRegistry(content);
+    const warnings = [];
+    const errors = [];
+    const oks = [];
+    // 重复 provide 条目 → 错误
+    const seen = new Map();
+    for (const e of entries)
+        seen.set(e.token, (seen.get(e.token) ?? 0) + 1);
+    for (const [token, n] of seen) {
+        if (n > 1)
+            errors.push(`units.ts 存在 ${n} 条重复 provide: '${token}'，请保留一条`);
+    }
+    const folderSet = new Set(folders);
+    const registeredTokens = new Set(entries.map((e) => e.token));
+    // 文件夹视角：命名规范 / 入口文件 / 是否登记
+    for (const name of folders) {
+        let broken = false;
+        if (!isValidName(name)) {
+            errors.push(`单元名「${name}」不符合 kebab-case 规范（units/${name}/）`);
+            broken = true;
+        }
+        if (!existsSync(join(unitsDir, name, 'index.ts'))) {
+            errors.push(`单元 units/${name}/ 缺少入口文件 index.ts`);
+            broken = true;
+        }
+        if (!registeredTokens.has(name)) {
+            warnings.push(`units/${name}/ 存在但 units.ts 未登记（运行 agentia g <type> ${name} 或手工登记）`);
+        }
+        else if (!broken) {
+            oks.push(`units/${name}：已登记且入口齐全`);
+        }
+    }
+    // 注册表视角：悬空单板（import 指向 ./units/ 但文件夹已不存在；add 引入的包无本地文件夹属正常）
+    for (const e of entries) {
+        if (!isValidName(e.token)) {
+            errors.push(`provide token「${e.token}」不符合 kebab-case 规范`);
+        }
+        const source = imports.get(e.ident);
+        if (source === undefined)
+            continue; // 无法定位 import（可能手工编写），跳过
+        if (source.startsWith('./units/')) {
+            const folder = source.split('/')[2];
+            if (folder !== undefined && !folderSet.has(folder)) {
+                warnings.push(`units.ts 条目 { provide: '${e.token}' } 指向 ${source}，但 units/${folder}/ 不存在（悬空单板，请删除条目或恢复目录）`);
+            }
+        }
+    }
+    console.log('agentia doctor —— 装配体检\n');
+    for (const msg of oks)
+        console.log(`  ✓ ${msg}`);
+    for (const msg of warnings)
+        console.log(`  警告：${msg}`);
+    for (const msg of errors)
+        console.log(`  错误：${msg}`);
+    console.log(`\n体检结果：${errors.length} 错误，${warnings.length} 警告`);
+    if (errors.length > 0) {
+        process.exitCode = 1;
+        return 1;
+    }
+    return 0;
+}

package/dist/registry.js

@@ -12,6 +12,18 @@ export function ensureRegistry(dir) {
     }
     return file;
 }
+/** 在标记区插入 import 行与条目行；标记行缺失时报错 */
+function insertAtMarkers(content, importLine, entryLine) {
+    const lines = content.split('\n');
+    const importsEnd = lines.findIndex((l) => l.trim() === IMPORTS_END_MARKER);
+    const entriesEnd = lines.findIndex((l) => l.trim() === ENTRIES_END_MARKER);
+    if (importsEnd === -1 || entriesEnd === -1) {
+        throw new RegistryError(`units.ts 缺少 ${IMPORTS_END_MARKER} / ${ENTRIES_END_MARKER} 标记行，无法自动登记；请手工维护该文件`);
+    }
+    lines.splice(entriesEnd, 0, entryLine);
+    lines.splice(importsEnd, 0, importLine);
+    return lines.join('\n');
+}
 /** 把单元登记进 dir/units.ts；已存在同名条目则跳过。标记行缺失时报错。 */
 export function registerUnit(dir, name) {
     const file = ensureRegistry(dir);
@@ -21,14 +33,19 @@ export function registerUnit(dir, name) {
     if (content.includes(`'./units/${name}/index.js'`) || content.includes(`provide: '${name}'`)) {
         return 'already';
     }
-    const lines = content.split('\n');
-    const importsEnd = lines.findIndex((l) => l.trim() === IMPORTS_END_MARKER);
-    const entriesEnd = lines.findIndex((l) => l.trim() === ENTRIES_END_MARKER);
-    if (importsEnd === -1 || entriesEnd === -1) {
-        throw new RegistryError(`units.ts 缺少 ${IMPORTS_END_MARKER} / ${ENTRIES_END_MARKER} 标记行，无法自动登记；请手工维护该文件`);
+    writeFileSync(file, insertAtMarkers(content, importLine, entryLine), 'utf8');
+    return 'registered';
+}
+/** 把第三方包（agentia add）登记进 dir/units.ts；token/import 来源已存在则跳过。 */
+export function registerPackage(dir, token, importSource) {
+    const file = ensureRegistry(dir);
+    const content = readFileSync(file, 'utf8');
+    const pascal = kebabToPascal(token);
+    const importLine = `import ${pascal} from '${importSource}';`;
+    const entryLine = `  { provide: '${token}', useClass: ${pascal} },`;
+    if (content.includes(`provide: '${token}'`) || content.includes(`from '${importSource}'`)) {
+        return 'already';
     }
-    lines.splice(entriesEnd, 0, entryLine);
-    lines.splice(importsEnd, 0, importLine);
-    writeFileSync(file, lines.join('\n'), 'utf8');
+    writeFileSync(file, insertAtMarkers(content, importLine, entryLine), 'utf8');
     return 'registered';
 }

package/dist/templates.js

@@ -45,7 +45,7 @@ export function projectPackageJson(name) {
             dev: 'tsx src/main.ts',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.0.2' },
+        dependencies: { '@migor/agentia': '^0.2.0' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@migor/cli",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 单元生成器",
   "type": "module",
   "bin": {
     "agentia": "./dist/cli.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "repository": "retrychx/agentia",
-  "keywords": ["agentia", "agent", "cli", "scaffold"],
-  "engines": { "node": ">=18" },
-  "publishConfig": { "access": "public" },
+  "keywords": [
+    "agentia",
+    "agent",
+    "cli",
+    "scaffold"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"