create-yss-spec 2.1.4 → 2.1.6

package/template/.pi/skills/yss-db2mybatis/scripts/db2mybatis.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Offline-first database metadata and YSS MyBatis scaffold generator.
+ * Node >=22 is required.  Live database drivers are deliberately resolved only
+ * from YSS_DB2MYBATIS_DRIVER_ROOT (or the caller's cwd); this tool never installs
+ * packages or modifies the driver directory.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { createRequire } from 'node:module';
+
+const AUDIT_COLUMNS = new Set(['created_by', 'created_date', 'last_modified_by', 'last_modified_date']);
+const LOGIC_DELETE_FIELDS = ['deleted', 'is_deleted'];
+const JAVA_IMPORTS = { BigDecimal: 'import java.math.BigDecimal;', LocalDateTime: 'import java.time.LocalDateTime;', LocalDate: 'import java.time.LocalDate;', LocalTime: 'import java.time.LocalTime;' };
+
+class SkillError extends Error {}
+const readText = (file) => fs.readFileSync(file, 'utf8');
+const writeText = (file, text) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, text, 'utf8'); };
+const loadJson = (file) => JSON.parse(readText(file));
+const pascal = (value) => String(value || '').split(/[_\-\s]+/).filter(Boolean).map((x) => x[0].toUpperCase() + x.slice(1).toLowerCase()).join('');
+const camel = (value) => { const x = pascal(value); return x ? x[0].toLowerCase() + x.slice(1) : x; };
+const upperFirst = (value) => value ? value[0].toUpperCase() + value.slice(1) : value;
+const lowerFirst = (value) => value ? value[0].toLowerCase() + value.slice(1) : value;
+const normalizeSqlType = (value) => String(value || '').trim().toLowerCase().replace(/\(.*\)/, '').replace(/\s+/g, ' ');
+const stripSqlType = (value) => normalizeSqlType(value).split(' ')[0] || '';
+const replaceTemplate = (text, values) => text.replace(/\$\{([^}]+)\}/g, (all, key) => Object.hasOwn(values, key) ? String(values[key]) : all);
+const normalizeTables = (value) => value ? value.split(',').map((x) => x.trim()).filter(Boolean) : null;
+const unquoteIdentifier = (value) => { let x = String(value).trim(); if ((x.startsWith('`') && x.endsWith('`')) || (x.startsWith('"') && x.endsWith('"'))) x = x.slice(1, -1); return x.includes('.') ? x.split('.').at(-1) : x; };
+const defaultPath = (root, relative) => path.resolve(root, relative);
+
+function filterTables(tables, include, exclude) {
+  const inc = include ? new RegExp(include) : null; const exc = exclude ? new RegExp(exclude) : null;
+  return tables.filter((table) => (!inc || inc.test(table.table_name)) && (!exc || !exc.test(table.table_name)));
+}
+function splitTopLevel(text, delimiter = ',') {
+  const values = []; let buffer = ''; let depth = 0; let quote = '';
+  for (let i = 0; i < text.length; i += 1) { const ch = text[i];
+    if (quote) { buffer += ch; if (ch === quote && text[i - 1] !== '\\') quote = ''; continue; }
+    if (["'", '"', '`'].includes(ch)) { quote = ch; buffer += ch; }
+    else if (ch === '(') { depth += 1; buffer += ch; }
+    else if (ch === ')') { depth = Math.max(0, depth - 1); buffer += ch; }
+    else if (ch === delimiter && depth === 0) { if (buffer.trim()) values.push(buffer.trim()); buffer = ''; }
+    else buffer += ch;
+  }
+  if (buffer.trim()) values.push(buffer.trim()); return values;
+}
+function parseSqlType(definition) {
+  let end = definition.length; const lower = definition.toLowerCase();
+  for (const pattern of [/\bnot\s+null\b/i, /\bnull\b/i, /\bdefault\b/i, /\bcomment\b/i, /\bprimary\s+key\b/i, /\bauto_increment\b/i, /\bgenerated\b/i, /\bunique\b/i, /\breferences\b/i, /\bconstraint\b/i, /\bcheck\b/i]) { const match = lower.match(pattern); if (match?.index !== undefined) end = Math.min(end, match.index); }
+  return definition.slice(0, end).trim();
+}
+function parseDdlTable(statement) {
+  const found = statement.match(/create\s+table\s+(?:if\s+not\s+exists\s+)?([`".\w]+)/i);
+  if (!found) throw new SkillError('DDL 解析失败：未识别 CREATE TABLE 语句');
+  const tableName = unquoteIdentifier(found[1]); const left = statement.indexOf('(', found.index + found[0].length);
+  if (left < 0) throw new SkillError(`DDL 解析失败：表 ${tableName} 缺少字段定义`);
+  let depth = 1; let quote = ''; let right = -1;
+  for (let i = left + 1; i < statement.length; i += 1) { const ch = statement[i]; if (quote) { if (ch === quote && statement[i - 1] !== '\\') quote = ''; } else if (["'", '"', '`'].includes(ch)) quote = ch; else if (ch === '(') depth += 1; else if (ch === ')' && --depth === 0) { right = i; break; } }
+  if (right < 0) throw new SkillError(`DDL 解析失败：表 ${tableName} 字段括号未闭合`);
+  const comment = statement.slice(right + 1).match(/comment\s*=\s*'([^']*)'/i)?.[1] || '';
+  const columns = []; const primaryKeys = [];
+  for (const raw of splitTopLevel(statement.slice(left + 1, right))) { const item = raw.trim().replace(/,+$/, ''); const lower = item.toLowerCase(); if (!item) continue;
+    if (lower.startsWith('primary key') || (lower.includes('constraint') && lower.includes('primary key'))) { const pkMatch = item.match(/\((.*?)\)/is); if (pkMatch) primaryKeys.push(...splitTopLevel(pkMatch[1]).map(unquoteIdentifier)); continue; }
+    if (/^(key|index|unique key|unique index|constraint|foreign key)\b/i.test(lower)) continue;
+    const colMatch = item.match(/^\s*([`".\w]+)\s+(.+)$/is); if (!colMatch) continue;
+    const name = unquoteIdentifier(colMatch[1]); const definition = colMatch[2].trim(); const inlinePk = /\bprimary\s+key\b/i.test(definition);
+    columns.push({ name, sql_type: parseSqlType(definition), nullable: !/\bnot\s+null\b/i.test(definition), primary: inlinePk, auto_increment: /\bauto_increment\b|\bidentity\b/i.test(definition), comment: definition.match(/comment\s+'([^']*)'/i)?.[1] || '' });
+    if (inlinePk && !primaryKeys.includes(name)) primaryKeys.push(name);
+  }
+  const pkSet = new Set(primaryKeys); for (const column of columns) if (pkSet.has(column.name)) { column.primary = true; column.nullable = false; }
+  return { table_name: tableName, table_comment: comment || tableName, primary_keys: primaryKeys, columns, indexes: [], foreign_keys: [] };
+}
+function metadataFromDdl(text, dbType = 'mysql', database = 'ddl', schema = null) {
+  const matches = [...text.matchAll(/\bcreate\s+table\b/ig)]; const tables = matches.map((match, index) => parseDdlTable(text.slice(match.index, matches[index + 1]?.index).trim()));
+  return { db_type: dbType, database, schema: schema || database, tables };
+}
+function readDdl(args) { if (args['ddl-file'] && args['ddl-sql']) throw new SkillError('不能同时使用 --ddl-file 和 --ddl-sql'); if (args['ddl-file']) return readText(args['ddl-file']); if (args['ddl-sql']) return args['ddl-sql']; throw new SkillError('请提供 --ddl-file 或 --ddl-sql'); }
+function javaType(type, mapping) { const normalized = normalizeSqlType(type); return mapping[normalized] || mapping[stripSqlType(type)] || 'String'; }
+function inferDomain(table, prefix) { return pascal(prefix && table.startsWith(prefix) ? table.slice(prefix.length) : table); }
+
+function parseArgs(argv) {
+  const [command, ...tokens] = argv; if (!command || command === '--help' || command === '-h') return { command: 'help', args: {} };
+  const args = {}; for (let i = 0; i < tokens.length; i += 1) { const token = tokens[i]; if (!token.startsWith('--')) throw new SkillError(`未知参数: ${token}`); const key = token.slice(2); if (['dry-run', 'overwrite', 'verbose', 'keep-audit-columns'].includes(key)) args[key] = true; else { if (tokens[i + 1] === undefined || tokens[i + 1].startsWith('--')) throw new SkillError(`参数 --${key} 需要值`); args[key] = tokens[++i]; } }
+  return { command, args };
+}
+const CONNECTION_OPTIONS = ['datasource-config', 'datasource-name', 'db-type', 'host', 'port', 'user', 'password', 'database', 'schema', 'tables', 'include-tables-regex', 'exclude-tables-regex'];
+const SCAFFOLD_OPTIONS = ['skill-root', 'base-package', 'domain-segment', 'domain-java-root', 'infra-java-root', 'table-prefix', 'po-template', 'domain-model-template', 'repository-template', 'domain-gateway-template', 'gateway-impl-template', 'convertor-template', 'type-mapping', 'convention-file', 'pk-strategy', 'keep-audit-columns', 'overwrite', 'dry-run', 'verbose', 'ddl-file', 'ddl-sql'];
+const COMMAND_OPTIONS = {
+  init: ['skill-root'],
+  extract: [...CONNECTION_OPTIONS, 'output'],
+  ddl2metadata: ['ddl-file', 'ddl-sql', 'db-type', 'database', 'schema', 'output'],
+  scaffold: [...CONNECTION_OPTIONS, 'metadata-file', ...SCAFFOLD_OPTIONS],
+  validate: ['datasource-config', ...SCAFFOLD_OPTIONS],
+};
+function validateOptionNames(command, args) {
+  if (!COMMAND_OPTIONS[command]) throw new SkillError(`不支持的命令: ${command}`);
+  const allowed = new Set(COMMAND_OPTIONS[command]);
+  for (const name of Object.keys(args)) if (!allowed.has(name)) throw new SkillError(`未知参数: --${name}`);
+}
+function requireArgs(args, names) { for (const name of names) if (args[name] === undefined || args[name] === '') throw new SkillError(`缺少 --${name}`); }
+function help() { console.log(`usage: node scripts/db2mybatis.mjs <init|extract|ddl2metadata|scaffold|validate> [options]\n\ncommands:\n  init          交互式配置向导\n  extract       提取数据库元数据\n  ddl2metadata  根据 DDL 文本生成 metadata.json\n  scaffold      根据元数据生成代码\n  validate      校验配置和模板`); }
+
+function mergeDatasource(args) { if (!args['datasource-config']) return args; const config = loadJson(args['datasource-config']); if (!args['datasource-name']) throw new SkillError('使用 --datasource-config 时必须传 --datasource-name'); const source = (config.datasources || {})[args['datasource-name']] || config[args['datasource-name']]; if (!source) throw new SkillError(`datasource 未找到: ${args['datasource-name']}`); for (const key of ['db-type', 'host', 'port', 'user', 'password', 'database', 'schema']) { const inputKey = key.replace('-', '_'); if ((args[key] === undefined || args[key] === '') && source[inputKey] !== undefined && source[inputKey] !== '') args[key] = source[inputKey]; } return args; }
+function requireConnection(args) { if (!args['db-type']) throw new SkillError('缺少 --db-type'); const missing = ['host', 'port', 'user', 'password', 'database'].filter((key) => !args[key]); if (missing.length) throw new SkillError(`缺少连接参数: ${missing.join(', ')}`); }
+function driver(name, dbType) { const root = process.env.YSS_DB2MYBATIS_DRIVER_ROOT || process.cwd(); try { return createRequire(path.join(path.resolve(root), 'package.json'))(name); } catch (error) { throw new SkillError(`${dbType} 需要 Node 驱动 ${name}；请在 YSS_DB2MYBATIS_DRIVER_ROOT（未设置时为当前工作目录）提供该依赖。本工具不会自动安装依赖。`); } }
+const mysqlQuery = async (connection, sql, values = []) => { const [rows] = await connection.execute(sql, values); return rows; };
+async function mysqlMetadata(args, dbType = 'mysql') {
+  const mysql = driver('mysql2/promise', dbType); let connection;
+  try { connection = await mysql.createConnection({ host: args.host, port: Number(args.port), user: args.user, password: args.password, database: args.database, charset: 'utf8mb4' }); const wanted = normalizeTables(args.tables); const tableRows = await mysqlQuery(connection, `SELECT TABLE_NAME, TABLE_COMMENT FROM information_schema.tables WHERE table_schema=? AND table_type='BASE TABLE'${wanted ? ` AND table_name IN (${wanted.map(() => '?').join(',')})` : ''} ORDER BY table_name`, [args.database, ...(wanted || [])]); const tables = [];
+    for (const row of tableRows) { const tableName = row.TABLE_NAME; const cols = await mysqlQuery(connection, `SELECT COLUMN_NAME, DATA_TYPE, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, EXTRA, COLUMN_COMMENT FROM information_schema.columns WHERE table_schema=? AND table_name=? ORDER BY ORDINAL_POSITION`, [args.database, tableName]); const indexRows = await mysqlQuery(connection, `SELECT INDEX_NAME AS index_name, COLUMN_NAME AS column_name, NON_UNIQUE = 0 AS is_unique, INDEX_NAME = 'PRIMARY' AS is_primary FROM information_schema.STATISTICS WHERE TABLE_SCHEMA=? AND TABLE_NAME=? ORDER BY INDEX_NAME, SEQ_IN_INDEX`, [args.database, tableName]); const fkRows = await mysqlQuery(connection, `SELECT CONSTRAINT_NAME AS fk_name, COLUMN_NAME AS column_name, REFERENCED_TABLE_NAME AS referenced_table, REFERENCED_COLUMN_NAME AS referenced_column FROM information_schema.KEY_COLUMN_USAGE WHERE TABLE_SCHEMA=? AND TABLE_NAME=? AND REFERENCED_TABLE_NAME IS NOT NULL ORDER BY CONSTRAINT_NAME, ORDINAL_POSITION`, [args.database, tableName]); const indexes = groupRows(indexRows, 'index_name', (x) => ({ name: x.index_name, columns: [], unique: Boolean(x.is_unique), primary: Boolean(x.is_primary) }), (result, x) => result.columns.push(x.column_name)); const foreignKeys = groupRows(fkRows, 'fk_name', (x) => ({ name: x.fk_name, columns: [], referenced_table: x.referenced_table, referenced_columns: [] }), (result, x) => { result.columns.push(x.column_name); result.referenced_columns.push(x.referenced_column); }); const columns = cols.map((col) => ({ name: col.COLUMN_NAME, sql_type: col.COLUMN_TYPE || col.DATA_TYPE, nullable: col.IS_NULLABLE === 'YES', primary: col.COLUMN_KEY === 'PRI', auto_increment: String(col.EXTRA || '').toLowerCase().includes('auto_increment'), comment: col.COLUMN_COMMENT || '' })); tables.push({ table_name: tableName, table_comment: row.TABLE_COMMENT || tableName, primary_keys: columns.filter((x) => x.primary).map((x) => x.name), columns, indexes, foreign_keys: foreignKeys }); }
+    return { db_type: dbType, database: args.database, schema: args.database, tables };
+  } finally { if (connection) await connection.end(); }
+}
+function groupRows(rows, key, factory, add) { const map = new Map(); for (const row of rows) { const value = row[key]; if (!map.has(value)) map.set(value, factory(row)); add(map.get(value), row); } return [...map.values()]; }
+async function postgresMetadata(args, dbType = 'postgres') {
+  const pg = driver('pg', dbType); const schema = args.schema || 'public'; const client = new pg.Client({ host: args.host, port: Number(args.port), user: args.user, password: args.password, database: args.database }); await client.connect(); try { const wanted = normalizeTables(args.tables); const tableResult = await client.query(`SELECT t.table_name, pgd.description AS table_comment FROM information_schema.tables t LEFT JOIN pg_catalog.pg_statio_all_tables st ON st.schemaname=t.table_schema AND st.relname=t.table_name LEFT JOIN pg_catalog.pg_description pgd ON pgd.objoid=st.relid AND pgd.objsubid=0 WHERE t.table_schema=$1 AND t.table_type='BASE TABLE'${wanted ? ' AND t.table_name = ANY($2)' : ''} ORDER BY t.table_name`, wanted ? [schema, wanted] : [schema]); const tables = [];
+    for (const tableRow of tableResult.rows) { const tableName = tableRow.table_name; const cols = (await client.query(`SELECT c.column_name,c.data_type,c.udt_name,c.is_nullable,pgd.description AS column_comment FROM information_schema.columns c LEFT JOIN pg_catalog.pg_statio_all_tables st ON st.schemaname=c.table_schema AND st.relname=c.table_name LEFT JOIN pg_catalog.pg_description pgd ON pgd.objoid=st.relid AND pgd.objsubid=c.ordinal_position WHERE c.table_schema=$1 AND c.table_name=$2 ORDER BY c.ordinal_position`, [schema, tableName])).rows; const pks = (await client.query(`SELECT kcu.column_name FROM information_schema.table_constraints tc JOIN information_schema.key_column_usage kcu ON tc.constraint_name=kcu.constraint_name AND tc.table_schema=kcu.table_schema AND tc.table_name=kcu.table_name WHERE tc.table_schema=$1 AND tc.table_name=$2 AND tc.constraint_type='PRIMARY KEY' ORDER BY kcu.ordinal_position`, [schema, tableName])).rows.map((x) => x.column_name); const indexRows = (await client.query(`SELECT ic.relname AS index_name,a.attname AS column_name,idx.indisunique AS is_unique,idx.indisprimary AS is_primary FROM pg_index idx JOIN pg_class ic ON idx.indexrelid=ic.oid JOIN pg_class t ON idx.indrelid=t.oid JOIN pg_namespace n ON t.relnamespace=n.oid JOIN pg_attribute a ON a.attrelid=t.oid AND a.attnum=ANY(idx.indkey) WHERE n.nspname=$1 AND t.relname=$2 ORDER BY ic.relname,a.attnum`, [schema, tableName])).rows; const fkRows = (await client.query(`SELECT tc.constraint_name AS fk_name,kcu.column_name AS column_name,ccu.table_name AS referenced_table,ccu.column_name AS referenced_column FROM information_schema.table_constraints tc JOIN information_schema.key_column_usage kcu ON tc.constraint_name=kcu.constraint_name JOIN information_schema.constraint_column_usage ccu ON ccu.constraint_name=tc.constraint_name WHERE tc.table_schema=$1 AND tc.table_name=$2 AND tc.constraint_type='FOREIGN KEY' ORDER BY tc.constraint_name,kcu.ordinal_position`, [schema, tableName])).rows; const pkSet = new Set(pks); tables.push({ table_name: tableName, table_comment: tableRow.table_comment || tableName, primary_keys: pks, columns: cols.map((x) => ({ name: x.column_name, sql_type: x.udt_name || x.data_type, nullable: x.is_nullable === 'YES', primary: pkSet.has(x.column_name), auto_increment: ['serial', 'bigserial'].includes(x.udt_name), comment: x.column_comment || '' })), indexes: groupRows(indexRows, 'index_name', (x) => ({ name: x.index_name, columns: [], unique: x.is_unique, primary: x.is_primary }), (x, row) => x.columns.push(row.column_name)), foreign_keys: groupRows(fkRows, 'fk_name', (x) => ({ name: x.fk_name, columns: [], referenced_table: x.referenced_table, referenced_columns: [] }), (x, row) => { x.columns.push(row.column_name); x.referenced_columns.push(row.referenced_column); }) }); }
+    return { db_type: dbType, database: args.database, schema, tables };
+  } finally { await client.end(); }
+}
+async function oracleMetadata(args) {
+  const oracle = driver('oracledb', 'oracle'); const connection = await oracle.getConnection({ user: args.user, password: args.password, connectString: `${args.host}:${Number(args.port)}/${args.database}` }); try { const wanted = normalizeTables(args.tables); const binds = {}; const queryNames = wanted?.map((x, i) => { binds[`t${i}`] = x.toUpperCase(); return `:t${i}`; }); const tableRows = (await connection.execute(`SELECT table_name FROM user_tables${queryNames ? ` WHERE table_name IN (${queryNames.join(',')})` : ''} ORDER BY table_name`, binds)).rows; const tables = [];
+    for (const row of tableRows) { const tableName = row[0]; const run = async (sql) => (await connection.execute(sql, { table_name: tableName })).rows; const colRows = await run(`SELECT utc.column_name,utc.data_type,utc.data_precision,utc.data_scale,utc.nullable,ucc.comments FROM user_tab_columns utc LEFT JOIN user_col_comments ucc ON utc.table_name=ucc.table_name AND utc.column_name=ucc.column_name WHERE utc.table_name=:table_name ORDER BY utc.column_id`); const pks = (await run(`SELECT cols.column_name FROM user_constraints cons JOIN user_cons_columns cols ON cons.constraint_name=cols.constraint_name WHERE cons.constraint_type='P' AND cons.table_name=:table_name ORDER BY cols.position`)).map((x) => x[0].toLowerCase()); const identity = new Set((await run(`SELECT column_name FROM user_tab_identity_cols WHERE table_name=:table_name`)).map((x) => x[0].toLowerCase())); const indexRows = await run(`SELECT ui.index_name,uic.column_name,ui.uniqueness='UNIQUE' AS is_unique,ui.index_name IN (SELECT uc.constraint_name FROM user_constraints uc WHERE uc.table_name=:table_name AND uc.constraint_type='P') AS is_primary FROM user_indexes ui JOIN user_ind_columns uic ON ui.index_name=uic.index_name WHERE ui.table_name=:table_name ORDER BY ui.index_name,uic.column_position`); const fkRows = await run(`SELECT uc.constraint_name,ucc.column_name,ruc.table_name,rucc.column_name FROM user_constraints uc JOIN user_cons_columns ucc ON uc.constraint_name=ucc.constraint_name JOIN user_constraints ruc ON uc.r_constraint_name=ruc.constraint_name JOIN user_cons_columns rucc ON ruc.constraint_name=rucc.constraint_name AND ucc.position=rucc.position WHERE uc.table_name=:table_name AND uc.constraint_type='R' ORDER BY uc.constraint_name,ucc.position`); const tableComment = (await run(`SELECT comments FROM user_tab_comments WHERE table_name=:table_name`))[0]?.[0] || tableName.toLowerCase(); const pkSet = new Set(pks); const typeFor = (x) => { const type = String(x[1] || '').toLowerCase(); if (type !== 'number') return type; return Number(x[3]) > 0 ? 'numeric' : Number(x[2]) <= 9 ? 'integer' : 'bigint'; }; tables.push({ table_name: tableName.toLowerCase(), table_comment: tableComment, primary_keys: pks, columns: colRows.map((x) => { const name = x[0].toLowerCase(); return { name, sql_type: typeFor(x), nullable: x[4] === 'Y', primary: pkSet.has(name), auto_increment: identity.has(name), comment: x[5] || '' }; }), indexes: groupRows(indexRows.map((x) => ({ index_name: x[0].toLowerCase(), column_name: x[1].toLowerCase(), is_unique: x[2], is_primary: x[3] })), 'index_name', (x) => ({ name: x.index_name, columns: [], unique: x.is_unique, primary: x.is_primary }), (x, row2) => x.columns.push(row2.column_name)), foreign_keys: groupRows(fkRows.map((x) => ({ fk_name: x[0].toLowerCase(), column_name: x[1].toLowerCase(), referenced_table: x[2].toLowerCase(), referenced_column: x[3].toLowerCase() })), 'fk_name', (x) => ({ name: x.fk_name, columns: [], referenced_table: x.referenced_table, referenced_columns: [] }), (x, row2) => { x.columns.push(row2.column_name); x.referenced_columns.push(row2.referenced_column); }) }); }
+    return { db_type: 'oracle', database: args.database, schema: args.user, tables };
+  } finally { await connection.close(); }
+}
+async function extract(args) { mergeDatasource(args); requireConnection(args); let metadata; try { if (['mysql', 'oceanbase'].includes(args['db-type'])) metadata = await mysqlMetadata(args, args['db-type']); else if (['postgres', 'opengauss'].includes(args['db-type'])) metadata = await postgresMetadata(args, args['db-type']); else if (args['db-type'] === 'oracle') metadata = await oracleMetadata(args); else throw new SkillError(`不支持的 db_type: ${args['db-type']}`); } catch (error) { if (error instanceof SkillError) throw error; throw new SkillError(`数据库连接失败: ${error.message}\n\n排查建议：\n  1. 检查数据库服务是否启动\n  2. 检查主机地址和端口是否正确\n  3. 检查用户名和密码是否正确\n  4. 检查数据库名是否正确\n  5. 检查网络连接是否正常\n`); }
+  const original = metadata.tables; metadata.tables = filterTables(original, args['include-tables-regex'], args['exclude-tables-regex']); if (!metadata.tables.length && original.length) throw new SkillError(`没有匹配到表。可用表：${original.map((x) => x.table_name).join(', ')}`); return metadata; }
+
+function normaliseScaffold(args) { const root = args['skill-root']; for (const [name, target] of Object.entries({ 'type-mapping': 'references/type-mapping.json', 'po-template': 'assets/po.java.template', 'domain-model-template': 'assets/domain_model.java.template', 'repository-template': 'assets/repository.java.template', 'domain-gateway-template': 'assets/domain_gateway.java.template', 'gateway-impl-template': 'assets/gateway_impl.java.template', 'convertor-template': 'assets/convertor.java.template' })) if (!args[name]) args[name] = defaultPath(root, target); const convention = { audit_columns: [...AUDIT_COLUMNS], logic_delete_fields: [...LOGIC_DELETE_FIELDS], pk_strategy: args['pk-strategy'] || 'error', page_method_name: 'page' }; if (args['convention-file']) Object.assign(convention, loadJson(args['convention-file'])); if (args['keep-audit-columns']) convention.audit_columns = []; args._convention = convention; }
+function validateTemplates(args) { const expected = { [args['po-template']]: ['${domain_name}', '${fields_block}', '${table_name}'], [args['domain-model-template']]: ['${domain_name}'], [args['repository-template']]: ['${domain_name}'], [args['domain-gateway-template']]: ['${domain_name}', '${pk_java_type}'], [args['gateway-impl-template']]: ['${domain_name}', '${repository_field_name}'], [args['convertor-template']]: ['${domain_name}'] }; for (const [file, tokens] of Object.entries(expected)) for (const token of tokens) if (!readText(file).includes(token)) throw new SkillError(`模板 ${file} 缺少占位符 ${token}`); }
+function buildFields(columns, mapping, skipped, forPo) { const lines = []; const usable = []; for (const column of columns) { if (skipped.has(column.name)) continue; usable.push(column); const field = camel(column.name); if (column.comment) lines.push(`/** ${column.comment} */`); if (forPo) lines.push(column.primary ? `@TableId(value = "${column.name}", type = IdType.${column.auto_increment ? 'AUTO' : 'ASSIGN_ID'})` : `    @TableField("${column.name}")`); lines.push(`    private ${javaType(column.sql_type, mapping)} ${field};`, ''); } while (lines.at(-1) === '') lines.pop(); return [lines.join('\n'), usable]; }
+function pickPrimary(table, columns, strategy) { const keys = table.primary_keys || []; if (keys.length > 1 && strategy === 'error') throw new SkillError(`表 ${table.table_name} 为联合主键 ${JSON.stringify(keys)}，当前 pk_strategy=error。可改用 --pk-strategy first`); if (keys.length) { const hit = columns.find((x) => x.name === keys[0]); if (hit) return hit; } return columns.find((x) => x.primary) || columns.find((x) => x.name === 'id') || { name: 'id', sql_type: 'bigint', primary: true, auto_increment: false }; }
+function importsFor(columns, mapping) { return [...new Set(columns.map((x) => JAVA_IMPORTS[javaType(x.sql_type, mapping)]).filter(Boolean))].sort().join('\n'); }
+function filePaths(args, domain) { const base = args['base-package'].replaceAll('.', '/'); const segment = args['domain-segment'] || domain.toLowerCase(); const domainRoot = path.join(args['domain-java-root'], base, 'domain', segment); const infra = path.join(args['infra-java-root'], base, 'repository'); return { domain_model: path.join(domainRoot, 'model', `${domain}.java`), domain_gateway: path.join(domainRoot, 'gateway', `${domain}Gateway.java`), po: path.join(infra, 'entity', `${domain}PO.java`), repo: path.join(infra, `${domain}Repository.java`), gateway_impl: path.join(infra, 'gateway', 'impl', `${domain}GatewayImpl.java`), convertor: path.join(infra, 'convertor', `${domain}Convertor.java`) }; }
+function writeJava(file, content, args) { if (fs.existsSync(file) && !args.overwrite) throw new SkillError(`文件已存在: ${file}. 如需覆盖请添加 --overwrite`); if (!args['dry-run']) writeText(file, `${content.trim()}\n`); }
+function generateTable(table, args, mapping) { const convention = args._convention; const domain = inferDomain(table.table_name, args['table-prefix'] || 't_'); const segment = args['domain-segment']; const modelPkg = `${args['base-package']}.domain.${segment || domain.toLowerCase()}.model`; const gatewayPkg = `${args['base-package']}.domain.${segment || domain.toLowerCase()}.gateway`; const [poFields, poColumns] = buildFields(table.columns || [], mapping, new Set(convention.audit_columns || []), true); const [domainFields, domainColumns] = buildFields(table.columns || [], mapping, new Set(convention.audit_columns || []), false); const primary = pickPrimary(table, domainColumns, convention.pk_strategy || 'error'); const pkName = camel(primary.name); const values = { base_package: args['base-package'], gateway_pkg: gatewayPkg, model_pkg: modelPkg, domain_segment: segment, table_name: table.table_name, table_comment: String(table.table_comment || table.table_name).replaceAll('*/', ''), domain_name: domain, fields_block: poFields, extra_imports: importsFor(poColumns, mapping), pk_java_type: javaType(primary.sql_type, mapping), pk_field_name: pkName, pk_getter: `get${upperFirst(pkName)}`, repository_field_name: `${lowerFirst(domain)}Repository`, method_add: `add${domain}`, method_update: `update${domain}`, method_delete: `delete${domain}`, method_get: `get${domain}ById`, method_page: `page${domain}`, logic_delete_condition: '' }; const logical = (convention.logic_delete_fields || []).find((x) => domainColumns.some((col) => col.name === x)); if (logical) values.logic_delete_condition = `        wrapper.eq(${domain}PO::get${upperFirst(camel(logical))}, 0);`; const templates = { domain_model: args['domain-model-template'], domain_gateway: args['domain-gateway-template'], po: args['po-template'], repo: args['repository-template'], gateway_impl: args['gateway-impl-template'], convertor: args['convertor-template'] }; const paths = filePaths(args, domain); const outputValues = { ...values, fields_block: domainFields, extra_imports: importsFor(domainColumns, mapping) }; const generated = []; for (const [kind, file] of Object.entries(paths)) { const templateValues = kind === 'domain_model' ? outputValues : values; writeJava(file, replaceTemplate(readText(templates[kind]), templateValues), args); generated.push(file); } return generated; }
+
+async function runInit(args) { requireArgs(args, ['skill-root']); const rl = readline.createInterface({ input, output }); const ask = async (label, fallback) => (await rl.question(`${label}${fallback ? ` [${fallback}]` : ''}: `)).trim() || fallback || ''; try { console.log('='.repeat(60) + '\n  yss-db2mybatis 配置向导\n' + '='.repeat(60)); const dbType = await ask('数据库类型（mysql/postgres/oracle）', 'postgres'); if (!['mysql', 'postgres', 'oracle'].includes(dbType)) throw new SkillError('数据库类型必须是 mysql、postgres 或 oracle'); const host = await ask('数据库主机地址', 'localhost'); const port = await ask('数据库端口', ({ mysql: '3306', postgres: '5432', oracle: '1521' })[dbType]); const user = await ask('数据库用户名', 'dmz'); const password = await ask('数据库密码', 'dmz'); const database = await ask('数据库名', 'yss_metadata'); const schema = dbType === 'postgres' ? await ask('Schema 名称', 'public') : null; const datasourceName = await ask('数据源名称', 'my-datasource'); const basePackage = await ask('基础包名', 'com.yss.metadata'); const segment = await ask('领域分段名', 'metadata'); const confirm = (await ask('确认生成配置文件? (y/n)', 'y')).toLowerCase(); if (!['y', 'yes', ''].includes(confirm)) { console.log('已取消'); return; } const file = path.join(os.tmpdir(), 'yss-db2mybatis', 'datasource-config.json'); const source = { db_type: dbType, host, port: Number(port), user, password, database }; if (schema) source.schema = schema; writeText(file, `${JSON.stringify({ datasources: { [datasourceName]: source } }, null, 2)}\n`); const metadata = path.join(os.tmpdir(), 'yss-db2mybatis', 'metadata.json'); console.log(`\n✅ 数据源配置文件已生成: ${file}\n\n1. 提取元数据:\n   node ${args['skill-root']}/scripts/db2mybatis.mjs extract \\\n     --datasource-config ${file} \\\n     --datasource-name ${datasourceName} \\\n     --include-tables-regex '.*' \\\n     --output ${metadata}\n\n2. 生成代码:\n   node ${args['skill-root']}/scripts/db2mybatis.mjs scaffold \\\n     --skill-root ${args['skill-root']} \\\n     --metadata-file ${metadata} \\\n     --base-package ${basePackage} \\\n     --domain-segment ${segment} \\\n     --domain-java-root ./domain \\\n     --infra-java-root ./infrastructure \\\n     --dry-run`); } finally { rl.close(); } }
+async function main() { let parsed; try { parsed = parseArgs(process.argv.slice(2)); if (parsed.command === 'help') return help(); const { command, args } = parsed; validateOptionNames(command, args); if (command === 'init') return runInit(args); if (command === 'ddl2metadata') { requireArgs(args, ['output']); const metadata = metadataFromDdl(readDdl(args), args['db-type'] || 'mysql', args.database || 'ddl', args.schema); if (!metadata.tables.length) throw new SkillError('DDL 中未识别到 CREATE TABLE'); writeText(args.output, `${JSON.stringify(metadata, null, 2)}\n`); console.log(`metadata written: ${args.output}\ntables: ${metadata.tables.length}`); return; } if (command === 'extract') { requireArgs(args, ['output']); const metadata = await extract(args); writeText(args.output, `${JSON.stringify(metadata, null, 2)}\n`); console.log(`metadata written: ${args.output}\ntables: ${metadata.tables.length}`); return; } if (!['scaffold', 'validate'].includes(command)) throw new SkillError(`不支持的命令: ${command}`); requireArgs(args, ['skill-root', 'base-package', 'domain-segment', 'domain-java-root', 'infra-java-root']); normaliseScaffold(args); validateTemplates(args); if (command === 'validate') { const checks = []; if (args['datasource-config']) { const config = loadJson(args['datasource-config']); if (!config.datasources || typeof config.datasources !== 'object' || Array.isArray(config.datasources)) throw new SkillError('datasource 配置文件缺少 datasources 对象'); checks.push('datasource-config'); } if (args['convention-file']) { const convention = loadJson(args['convention-file']); if (!convention || typeof convention !== 'object' || Array.isArray(convention)) throw new SkillError('convention 文件必须为 JSON 对象'); checks.push('convention-file'); } console.log(`validate passed\nchecks: ${[...checks, 'templates'].join(', ')}`); return; } let metadata; if (args['metadata-file']) { metadata = loadJson(args['metadata-file']); } else if (args['ddl-file'] || args['ddl-sql']) { metadata = metadataFromDdl(readDdl(args), args['db-type'] || 'mysql', args.database || 'ddl', args.schema); } else metadata = await extract(args); const tables = filterTables(metadata.tables || [], args['include-tables-regex'], args['exclude-tables-regex']); if (!tables.length) throw new SkillError('没有匹配到可生成的表'); const mapping = loadJson(args['type-mapping']); const files = tables.flatMap((table) => generateTable(table, args, mapping)); for (const file of files) console.log(`${args['dry-run'] ? 'planned' : 'generated'}: ${file}`); console.log(`done. file count: ${files.length}`); } catch (error) { console.error(`error: ${error.message}`); process.exitCode = 2; } }
+
+await main();

package/template/.pi/skills/yss-db2mybatis/scripts/db2mybatis.test.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+
+const skillRoot = path.resolve(import.meta.dirname, '..');
+const script = path.join(skillRoot, 'scripts', 'db2mybatis.mjs');
+const run = (args, cwd = process.cwd()) => spawnSync(process.execPath, [script, ...args], { cwd, encoding: 'utf8' });
+const temp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'yss-db2mybatis-node-'));
+const scaffoldArgs = (root, metadata, extra = []) => ['scaffold', '--skill-root', skillRoot, '--metadata-file', metadata, '--base-package', 'com.yss.demo', '--domain-segment', 'example', '--domain-java-root', path.join(root, 'domain'), '--infra-java-root', path.join(root, 'infra'), ...extra];
+
+test('DDL 转 metadata，并保留主键、类型与注释', () => {
+  const root = temp(); const metadata = path.join(root, 'metadata.json');
+  const result = run(['ddl2metadata', '--ddl-sql', "CREATE TABLE t_order (id bigint NOT NULL COMMENT '主键', amount decimal(10,2), PRIMARY KEY (id)) COMMENT='订单';", '--db-type', 'mysql', '--database', 'demo', '--output', metadata]);
+  assert.equal(result.status, 0, result.stderr); const parsed = JSON.parse(fs.readFileSync(metadata, 'utf8'));
+  assert.equal(parsed.tables[0].table_name, 't_order'); assert.deepEqual(parsed.tables[0].primary_keys, ['id']); assert.equal(parsed.tables[0].columns[1].sql_type, 'decimal(10,2)');
+});
+
+test('scaffold dry-run 不写文件，正常生成拒绝既有目标', () => {
+  const root = temp(); const metadata = path.join(root, 'metadata.json');
+  fs.writeFileSync(metadata, JSON.stringify({ tables: [{ table_name: 't_order', table_comment: '订单', primary_keys: ['id'], columns: [{ name: 'id', sql_type: 'bigint', primary: true, nullable: false, auto_increment: false }], indexes: [], foreign_keys: [] }] }));
+  const dryRun = run(scaffoldArgs(root, metadata, ['--dry-run'])); assert.equal(dryRun.status, 0, dryRun.stderr); assert.match(dryRun.stdout, /planned:/); assert.equal(fs.existsSync(path.join(root, 'domain')), false);
+  const generated = run(scaffoldArgs(root, metadata)); assert.equal(generated.status, 0, generated.stderr); const again = run(scaffoldArgs(root, metadata)); assert.equal(again.status, 2); assert.match(again.stderr, /文件已存在/);
+});
+
+test('非法参数和缺失数据库驱动均以退出码 2 失败', () => {
+  const invalid = run(['ddl2metadata', '--output', path.join(temp(), 'out.json')]); assert.equal(invalid.status, 2); assert.match(invalid.stderr, /请提供 --ddl-file 或 --ddl-sql/);
+  const unknown = run(['ddl2metadata', '--ddl-sql', 'CREATE TABLE t_x (id bigint)', '--output', path.join(temp(), 'out.json'), '--unexpected', 'x']); assert.equal(unknown.status, 2); assert.match(unknown.stderr, /未知参数/);
+  const missing = run(['extract', '--db-type', 'mysql', '--host', '127.0.0.1', '--port', '3306', '--user', 'u', '--password', 'p', '--database', 'd', '--output', path.join(temp(), 'out.json')], temp()); assert.equal(missing.status, 2); assert.match(missing.stderr, /YSS_DB2MYBATIS_DRIVER_ROOT/);
+});

package/template/.pi/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -25,17 +25,17 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 
 1. 确认项目名、基础包名、输出目录、数据库类型。
    Harness 内输出目录必须是 `apps/backend/` 容器，生成器再以 `project_name` 创建 `apps/backend/<project>/`；禁止使用 `app/backend/`、`app/frontend/` 或把 `apps/backend/` 之外的容器根当作后端项目根。
-2. 运行 `scripts/generate_scaffold.py` 生成骨架。
+2. 运行 `node scripts/generate_scaffold.mjs` 生成骨架。
 3. 检查生成的模块名、POM、基础配置文件和包路径。
 4. 由生命周期受控工作单元在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；生成器打印的下一步命令不构成验证证据。
 5. 如需继续细化，再追加其他 YSS skill 补全领域、仓储和 Web。
 
-受控验证命令由本 skill 的 `scripts/run_scaffold_verification.py` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、耗时、执行时间和 `scaffold-verification.json`；任何一条命令失败或未执行都必须阻断。
+受控验证命令由本 skill 的 `node scripts/run_scaffold_verification.mjs` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、耗时、执行时间和 `scaffold-verification.json`；任何一条命令失败或未执行都必须阻断。
 
 ## 推荐命令
 
 ```bash
-python3 scripts/generate_scaffold.py \
+node scripts/generate_scaffold.mjs \
   --project-name my-service \
   --base-package com.yss.myservice \
   --output-dir /path/to/implementation-repo \
@@ -82,8 +82,8 @@ python3 scripts/generate_scaffold.py \
 
 ## 按需读取
 
-- 主脚本：`scripts/generate_scaffold.py`
-- 受控验证器：`scripts/run_scaffold_verification.py`
+- 主脚本：`scripts/generate_scaffold.mjs`
+- 受控验证器：`scripts/run_scaffold_verification.mjs`
 - 模板目录：`assets/templates/`
 - 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
 

package/template/.pi/skills/yss-ddd-scaffold-generator/references/USAGE_EXAMPLES.md

@@ -9,7 +9,7 @@
 cd yss-datamiddle-scaffold
 
 # 生成项目
-python3 .agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.py \
+node .agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs \
   --project-name user-service \
   --base-package com.yss.user \
   --output-dir /path/to/implementation-repo \
@@ -53,7 +53,7 @@ cd output/user-service
 从生命周期工作目录执行固定验证器；它会在项目 evidence 目录实际运行三条 wrapper 命令并写入结果，不能用生成器打印的命令替代：
 
 ```bash
-python3 .agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.py \
+node .agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs \
   --project-root /path/to/implementation-repo/user-service \
   --evidence-dir /path/to/implementation-repo/user-service/docs/evidence/scaffold
 ```

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/** YSS DDD 后端纯工程骨架生成器；只生成工程结构，不生成任何业务行为。 */
+import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile, copyFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
+const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
+const COMMANDS = ["./mvnw validate", "./mvnw test", "./mvnw package"];
+
+function fail(message) { throw new Error(message); }
+function isoNow() { return new Date().toISOString(); }
+function localDate() { return new Date().toISOString().slice(0, 10); }
+function backupStamp() { return new Date().toISOString().replace(/[-:TZ.]/g, ""); }
+function usage(error) {
+  const text = `YSS DDD 脚手架生成器\n\n` +
+    `用法: node scripts/generate_scaffold.mjs --project-name <kebab-case> --base-package <package> --output-dir <dir> --contract-file <json> [选项]\n\n` +
+    `必填合同元数据: --contract-id --contract-version --approval-ref --router-draft-ref --persisted-ref\n` +
+    `选项: --database mysql, --force, --overwrite-scope <scope>, --rollback-ref <ref>\n` +
+    `--with-example 已禁用；--without-example 是兼容的无操作参数。`;
+  if (error) process.stderr.write(`错误: ${error}\n\n`);
+  process.stdout.write(`${text}\n`);
+}
+
+function parseArgs(argv) {
+  const options = { database: "mysql", force: false, withExample: false };
+  const mapping = new Map([
+    ["--project-name", "projectName"], ["--base-package", "basePackage"], ["--output-dir", "outputDir"],
+    ["--database", "database"], ["--contract-id", "contractId"], ["--contract-version", "contractVersion"],
+    ["--approval-ref", "approvalRef"], ["--router-draft-ref", "routerDraftRef"], ["--persisted-ref", "persistedRef"],
+    ["--contract-file", "contractFile"], ["--overwrite-scope", "overwriteScope"], ["--rollback-ref", "rollbackRef"],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    let token = argv[index];
+    if (token === "--help" || token === "-h") { options.help = true; continue; }
+    if (token === "--force") { options.force = true; continue; }
+    if (token === "--with-example") { options.withExample = true; continue; }
+    if (token === "--without-example") { options.withExample = false; continue; }
+    const equal = token.indexOf("=");
+    let value;
+    if (equal !== -1) { value = token.slice(equal + 1); token = token.slice(0, equal); }
+    if (!mapping.has(token)) fail(`不支持的参数: ${token}`);
+    if (value === undefined) value = argv[++index];
+    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
+    options[mapping.get(token)] = value;
+  }
+  if (options.help) return options;
+  for (const [flag, key] of mapping) {
+    if (["database", "overwriteScope", "rollbackRef", "contractId", "contractVersion", "approvalRef", "routerDraftRef", "persistedRef"].includes(key)) continue;
+    if (!options[key]) fail(`缺少必填参数: ${flag}`);
+  }
+  if (options.database !== "mysql") fail("参数 --database 只支持 mysql");
+  if (!/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("项目名称必须是 kebab-case 格式 (例如: user-service)");
+  if (!/^[a-z](?:[a-z0-9]*)(?:\.[a-z](?:[a-z0-9]*)?)*$/.test(options.basePackage)) fail("包名格式不正确 (例如: com.yss.user)");
+  if (options.contractVersion !== undefined && (!/^\d+$/.test(options.contractVersion) || Number(options.contractVersion) < 1)) fail("--contract-version(必须为正整数)");
+  if (options.contractVersion !== undefined) options.contractVersion = Number(options.contractVersion);
+  if (options.withExample) fail("--with-example 已禁用；业务代码必须由批准的 YSS Slice skill 逐切片生成");
+  return options;
+}
+
+async function exists(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function isFile(target) { try { return (await stat(target)).isFile(); } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function nonEmpty(target) { const info = await lstat(target); return !info.isDirectory() || (await readdir(target)).length > 0; }
+async function readJson(target, message) { try { return JSON.parse(await readFile(target, "utf8")); } catch (error) { fail(`${message}: ${target}`); } }
+async function writeText(target, content) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content, "utf8"); }
+function isPresent(value) { return value !== undefined && value !== null && value !== "" && (!Array.isArray(value) || value.length > 0); }
+
+class ScaffoldGenerator {
+  constructor(options) {
+    this.options = options;
+    this.projectName = options.projectName;
+    this.basePackage = options.basePackage;
+    this.outputDir = path.resolve(options.outputDir);
+    this.contractFile = path.resolve(options.contractFile);
+    this.finalProjectRoot = path.join(this.outputDir, this.projectName);
+    this.projectRoot = this.finalProjectRoot;
+    this.templateRoot = path.join(SKILL_ROOT, "assets", "templates");
+    this.configTemplateDir = path.join(this.templateRoot, "config");
+    this.pomTemplateDir = path.join(this.templateRoot, "pom");
+    this.packagePath = this.basePackage.replaceAll(".", path.sep);
+    this.author = process.env.USER || "yss-team";
+    this.date = localDate();
+    this.groupId = this.basePackage.split(".").slice(0, 2).join(".");
+    this.dbName = this.projectName.replaceAll("-", "_");
+    this.scaffoldContract = undefined;
+  }
+
+  async generate() {
+    await this.validateHarnessOutputLayout();
+    if (await exists(this.finalProjectRoot) && !this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    await this.validateContractMetadata();
+    if (await exists(this.finalProjectRoot) && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
+    await mkdir(this.outputDir, { recursive: true });
+    const stagingRoot = await mkdtemp(path.join(this.outputDir, `.${this.projectName}.staging-`));
+    this.projectRoot = path.join(stagingRoot, this.projectName);
+    try {
+      console.log(`🚀 开始生成项目: ${this.projectName}\n📦 基础包名: ${this.basePackage}\n📁 输出目录: ${this.outputDir}\n`);
+      await this.createProjectStructure(); await this.generatePomFiles(); await this.generateConfigFiles();
+      this.generateDatabaseScripts(); await this.generateDocumentation(); await this.writeGenerationManifest();
+      await this.copyWrapperFiles(); await this.validateGeneratedArtifacts();
+      let backupPath;
+      if (await exists(this.finalProjectRoot)) { backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`); await rename(this.finalProjectRoot, backupPath); }
+      await rename(this.projectRoot, this.finalProjectRoot); this.projectRoot = this.finalProjectRoot;
+      console.log(`\n✅ 项目生成完成!\n📂 项目位置: ${this.projectRoot}`);
+      if (backupPath) console.log(`♻️ 原项目备份: ${backupPath}`);
+      console.log(`\n🎯 下一步:\n  cd ${this.projectRoot}\n  ./mvnw validate\n  ./mvnw test\n  ./mvnw package\n  ./mvnw spring-boot:run -pl ${this.projectName}-bootstrap`);
+    } catch (error) { await rm(stagingRoot, { recursive: true, force: true }); throw error; }
+  }
+
+  async validateHarnessOutputLayout() {
+    const relative = path.relative(REPOSITORY_ROOT, this.outputDir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) return; // 外部实现仓库。
+    const parts = relative.split(path.sep).filter(Boolean);
+    if (parts.length >= 2 && parts[0] === "app" && ["backend", "frontend"].includes(parts[1])) fail("禁止使用单数 app/backend 或 app/frontend 作为工程生成路径；Harness 内后端脚手架必须以 apps/backend 为父容器");
+    if (parts.length === 2 && parts[0] === "apps" && parts[1] === "backend") return;
+    if (parts.length >= 2 && parts[0] === "apps" && parts[1] === "frontend") fail("后端脚手架不能输出到 apps/frontend；请使用外部后端仓库或 apps/backend");
+    fail("当前 Harness 内生成后端工程时，输出目录必须是 apps/backend；生成器会以 project_name 创建 apps/backend/<project>/");
+  }
+
+  async validateContractMetadata() {
+    if (!await isFile(this.contractFile)) fail("必须提供已持久化的结构化脚手架合同 JSON 文件: --contract-file");
+    const contract = await readJson(this.contractFile, "脚手架合同文件无法读取或不是合法 JSON");
+    if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
+    const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--router-draft-ref", this.options.routerDraftRef], ["--persisted-ref", this.options.persistedRef]];
+    const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
+    if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);
+    const required = ["schema_version", "contract_id", "contract_version", "slice_id", "status", "router_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "target_git_url_or_output_dir", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "overwrite_policy"];
+    const missingFields = required.filter((field) => !isPresent(contract[field]));
+    if (missingFields.length) fail(`脚手架合同缺少结构化字段: ${missingFields.join(", ")}`);
+    if (contract.schema_version !== 1 || contract.status !== "approved") fail("脚手架合同必须是 schema_version=1 且已由生命周期批准");
+    if (contract.contract_id !== this.options.contractId) fail("--contract-id 与脚手架合同不一致");
+    if (contract.contract_version !== this.options.contractVersion) fail("--contract-version 与脚手架合同不一致");
+    if (contract.current_version !== contract.contract_version) fail("脚手架合同版本不是当前版本");
+    if (contract.router_draft_ref !== this.options.routerDraftRef) fail("--router-draft-ref 与脚手架合同不一致");
+    if (contract.persisted_ref !== this.options.persistedRef) fail("--persisted-ref 与脚手架合同不一致");
+    if (contract.lifecycle_approval_ref !== this.options.approvalRef) fail("--approval-ref 与脚手架合同不一致");
+    if (contract.scaffold_status !== "required") fail("脚手架生成器只接受 scaffold_status=required");
+    if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((field) => Array.isArray(contract[field]) && contract[field].length)) fail("脚手架合同的 allowed_write_paths、expected_evidence_files、verification_commands 必须非空");
+    if (!contract.expected_evidence_files.map(String).join(" ").includes(".yss/scaffold-generation.json")) fail("脚手架合同 expected_evidence_files 必须包含 .yss/scaffold-generation.json");
+    const targetRef = String(contract.target_git_url_or_output_dir);
+    if (!targetRef.includes("://") && !targetRef.startsWith("git@") && path.resolve(targetRef) !== this.outputDir) fail("脚手架合同目标目录与 --output-dir 不一致");
+    if (JSON.stringify(contract.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架合同验证命令必须固定为三条项目根目录 ./mvnw 命令");
+    const approval = contract.approval;
+    if (!approval || typeof approval !== "object" || ["approval_ref", "approver", "persisted_ref", "current_version"].some((field) => !isPresent(approval[field]))) fail("脚手架合同 approval 记录不完整");
+    if (approval.approval_ref !== this.options.approvalRef || approval.persisted_ref !== this.options.persistedRef) fail("脚手架合同 approval 引用与命令参数不一致");
+    if (approval.current_version !== this.options.contractVersion) fail("脚手架合同 approval 不是当前版本");
+    const workUnit = contract.work_unit;
+    const workFields = ["id", "behavior", "primary_skill", "supporting_skills", "tdd_mode", "allowed_write_paths", "expected_evidence", "verification_commands", "controlled_generation"];
+    if (!workUnit || typeof workUnit !== "object" || workFields.some((field) => !isPresent(workUnit[field]))) fail("脚手架合同 work_unit 结构不完整");
+    if (workUnit.primary_skill !== "yss-ddd-scaffold-generator" || workUnit.tdd_mode !== "controlled-generation" || workUnit.controlled_generation !== true) fail("脚手架合同 work_unit 必须绑定本 skill 和 controlled-generation");
+    if (JSON.stringify(workUnit.verification_commands) !== JSON.stringify(contract.verification_commands) || JSON.stringify(workUnit.allowed_write_paths) !== JSON.stringify(contract.allowed_write_paths)) fail("脚手架合同 work_unit 与根级验证/写路径约束不一致");
+    const overwrite = contract.overwrite_policy;
+    if (!overwrite || typeof overwrite !== "object" || ["force_allowed", "overwrite_scope", "rollback_ref"].some((field) => !(field in overwrite))) fail("脚手架合同 overwrite_policy 结构不完整");
+    this.scaffoldContract = contract;
+  }
+
+  validateForceMetadata() {
+    if (!isPresent(this.options.overwriteScope) || !isPresent(this.options.rollbackRef)) fail("覆盖非空目录必须提供当前批准合同的覆盖范围和回滚引用: --overwrite-scope, --rollback-ref");
+    const policy = this.scaffoldContract.overwrite_policy;
+    if (policy.force_allowed !== true) fail("脚手架合同未批准非空目录覆盖");
+    if (policy.overwrite_scope !== this.options.overwriteScope) fail("--overwrite-scope 与脚手架合同不一致");
+    if (policy.rollback_ref !== this.options.rollbackRef) fail("--rollback-ref 与脚手架合同不一致");
+  }
+
+  templateVars() {
+    const database = this.options.database;
+    const dependency = database === "mysql" ? `<dependency>\n    <groupId>com.mysql</groupId>\n    <artifactId>mysql-connector-j</artifactId>\n    <version>8.4.0</version>\n    <scope>compile</scope>\n</dependency>` : "";
+    return { project_name: this.projectName, base_package: this.basePackage, group_id: this.groupId, project_description: `${this.projectName} service`, author: this.author, date: this.date, database, driver_class: "com.mysql.cj.jdbc.Driver", db_name: this.dbName, jdbc_url: `jdbc:mysql://localhost:3306/${this.dbName}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai`, db_dependency: dependency };
+  }
+  render(text) { let output = text; for (const [key, value] of Object.entries(this.templateVars())) output = output.replaceAll(`{{${key}}}`, String(value)); return output; }
+  async renderTemplate(template, output) { if (!await isFile(template)) fail(`模板文件不存在: ${template}`); await writeText(output, this.render(await readFile(template, "utf8"))); }
+
+  async createProjectStructure() {
+    console.log("📁 创建项目目录结构...");
+    for (const module of ["domain", "application", "infrastructure", "adapter", "bootstrap"]) {
+      const root = path.join(this.projectRoot, `${this.projectName}-${module}`);
+      await Promise.all([mkdir(path.join(root, "src/main/java", this.packagePath), { recursive: true }), mkdir(path.join(root, "src/main/resources"), { recursive: true }), mkdir(path.join(root, "src/test/java", this.packagePath), { recursive: true })]);
+      console.log(`  ✓ ${this.projectName}-${module}`);
+    }
+    await mkdir(path.join(this.projectRoot, `${this.projectName}-adapter`, `${this.projectName}-web`, "src/main/java", this.packagePath, "rest"), { recursive: true });
+    await mkdir(path.join(this.projectRoot, "db"), { recursive: true });
+    console.log(`  ✓ ${this.projectName}-adapter/${this.projectName}-web\n  ✓ db`);
+  }
+  async generatePomFiles() {
+    console.log("\n📝 生成 Maven POM 文件...");
+    const pom = (name) => path.join(this.pomTemplateDir, name);
+    const target = (module) => path.join(this.projectRoot, module, "pom.xml");
+    await Promise.all([[pom("parent-pom.xml.template"), path.join(this.projectRoot, "pom.xml")], [pom("domain-pom.xml.template"), target(`${this.projectName}-domain`)], [pom("application-pom.xml.template"), target(`${this.projectName}-application`)], [pom("infrastructure-pom.xml.template"), target(`${this.projectName}-infrastructure`)], [pom("adapter-pom.xml.template"), target(`${this.projectName}-adapter`)], [pom("web-pom.xml.template"), target(path.join(`${this.projectName}-adapter`, `${this.projectName}-web`))], [pom("bootstrap-pom.xml.template"), target(`${this.projectName}-bootstrap`)]].map(([from, to]) => this.renderTemplate(from, to)));
+    console.log("  ✓ 父级 pom.xml\n  ✓ domain pom.xml\n  ✓ application pom.xml\n  ✓ infrastructure pom.xml\n  ✓ adapter pom.xml\n  ✓ web pom.xml\n  ✓ bootstrap pom.xml");
+  }
+  async generateConfigFiles() {
+    console.log("\n⚙️  生成配置文件..."); const base = path.join(this.projectRoot, `${this.projectName}-bootstrap`, "src/main/resources");
+    await Promise.all([["application.yml.template", "application.yml"], ["logback-spring.xml.template", "logback-spring.xml"]].map(([from, to]) => this.renderTemplate(path.join(this.configTemplateDir, from), path.join(base, to))));
+    console.log("  ✓ application.yml\n  ✓ logback-spring.xml");
+  }
+  generateDatabaseScripts() { console.log("\n🗃️  保留数据库目录布局...\n  ✓ db/（业务 schema 和初始化数据由批准切片合同生成）"); }
+  async generateDocumentation() {
+    console.log("\n📚 生成项目文档...");
+    await writeText(path.join(this.projectRoot, "README.md"), this.render("# {{project_name}}\n\n## 模块说明\n\n- {{project_name}}-domain\n- {{project_name}}-application\n- {{project_name}}-infrastructure\n- {{project_name}}-adapter\n- {{project_name}}-bootstrap\n\n业务 API、领域模型、数据结构和权限行为必须在冻结的 Slice Implementation Contract 下，由对应 YSS skill 逐切片实现。\n\n## 快速开始\n\n```bash\ncd {{project_name}}\n./mvnw clean compile\n./mvnw spring-boot:run -pl {{project_name}}-bootstrap\n```\n"));
+    console.log("  ✓ README.md");
+  }
+  async writeGenerationManifest() {
+    const contract = this.scaffoldContract;
+    const manifest = { schema_version: 1, contract_id: this.options.contractId, contract_version: this.options.contractVersion, approval_ref: this.options.approvalRef, router_draft_ref: this.options.routerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, slice_id: contract.slice_id, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, database: this.options.database, generation_mode: "controlled-generation", force: this.options.force, overwrite_scope: this.options.overwriteScope, rollback_ref: this.options.rollbackRef, verification_commands: COMMANDS, generated_at: isoNow() };
+    await writeText(path.join(this.projectRoot, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`); console.log("  ✓ .yss/scaffold-generation.json");
+  }
+  async copyWrapperFiles() {
+    const wrapper = path.join(SKILL_ROOT, "assets", "wrapper");
+    for (const file of ["mvnw", "mvnw.cmd"]) { const source = path.join(wrapper, file); if (await exists(source)) { const target = path.join(this.projectRoot, file); await mkdir(path.dirname(target), { recursive: true }); await copyFile(source, target); await chmod(target, (await stat(source)).mode); } }
+    if (await exists(path.join(wrapper, ".mvn"))) await cp(path.join(wrapper, ".mvn"), path.join(this.projectRoot, ".mvn"), { recursive: true, force: true });
+  }
+  async validateGeneratedArtifacts() {
+    const required = [path.join(this.projectRoot, "pom.xml"), path.join(this.projectRoot, `${this.projectName}-bootstrap`, "pom.xml"), path.join(this.projectRoot, "mvnw"), path.join(this.projectRoot, ".yss", "scaffold-generation.json")];
+    const missing = []; for (const target of required) if (!await isFile(target)) missing.push(target); if (missing.length) fail(`生成产物缺失: ${missing.join(", ")}`);
+    const manifest = await readJson(required[3], "脚手架生成元数据清单无法读取");
+    if (manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || manifest.current_version !== this.options.contractVersion || manifest.generation_mode !== "controlled-generation" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准合同或固定验证命令不一致");
+    const stack = [this.projectRoot], binary = new Set([".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"]);
+    while (stack.length) { const dir = stack.pop(); for (const entry of await readdir(dir, { withFileTypes: true })) { const target = path.join(dir, entry.name); if (entry.isDirectory()) { stack.push(target); continue; } if (!entry.isFile() || binary.has(path.extname(entry.name))) continue; const content = await readFile(target, "utf8"); if (content.includes("{{") || content.includes("root/root")) fail(`生成文件包含未替换占位符或明文凭据: ${target}`); } }
+  }
+}
+
+async function main() { let options; try { options = parseArgs(process.argv.slice(2)); if (options.help) { usage(); return 0; } await new ScaffoldGenerator(options).generate(); return 0; } catch (error) { process.stderr.write(`\n❌ 生成失败: ${error.message}\n`); return 1; } }
+process.exitCode = await main();

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/** 在生成项目根目录实际执行 YSS 脚手架的固定验证命令并留证。 */
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+
+const PHASES = ["validate", "test", "package"];
+const COMMANDS = PHASES.map((phase) => `./mvnw ${phase}`);
+const isoNow = () => new Date().toISOString();
+async function isFile(target) { try { return (await stat(target)).isFile(); } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function writeText(target, content) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content, "utf8"); }
+function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.length; index += 1) { let token = argv[index]; if (token === "--help" || token === "-h") { result.help = true; continue; } const equals = token.indexOf("="); let value; if (equals !== -1) { value = token.slice(equals + 1); token = token.slice(0, equals); } if (!["--project-root", "--evidence-dir"].includes(token)) throw new Error(`不支持的参数: ${token}`); if (value === undefined) value = argv[++index]; if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`); result[token === "--project-root" ? "projectRoot" : "evidenceDir"] = path.resolve(value); } if (result.help) return result; if (!result.projectRoot || !result.evidenceDir) throw new Error("必须提供 --project-root 和 --evidence-dir"); return result; }
+function validateManifest(manifest) {
+  const required = ["schema_version", "contract_id", "contract_version", "slice_id", "approval_ref", "approver", "lifecycle_approval_ref", "router_draft_ref", "persisted_ref", "contract_file_ref", "current_version", "allowed_write_paths", "expected_evidence_files", "verification_commands", "generation_mode"];
+  const missing = required.filter((field) => manifest[field] === undefined || manifest[field] === null || manifest[field] === "");
+  if (manifest.generation_mode !== "controlled-generation" || missing.length) throw new Error(`脚手架生成元数据清单不完整或不是 controlled-generation: ${missing.join(", ")}`);
+  if (manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
+  if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
+}
+function execute(wrapper, phase, cwd) { return new Promise((resolve) => { const child = spawn(wrapper, [phase], { cwd, stdio: ["ignore", "pipe", "pipe"] }); let stdout = "", stderr = ""; child.stdout.on("data", (chunk) => { stdout += chunk; }); child.stderr.on("data", (chunk) => { stderr += chunk; }); child.on("error", (error) => resolve({ exitCode: 127, stdout: "", stderr: String(error) })); child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr })); }); }
+export async function run(projectRoot, evidenceDir) {
+  const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
+  if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
+  let manifest; try { manifest = JSON.parse(await readFile(manifestPath, "utf8")); } catch { throw new Error(`脚手架生成元数据清单无法读取或不是合法 JSON: ${manifestPath}`); }
+  validateManifest(manifest); await mkdir(evidenceDir, { recursive: true }); const commands = [];
+  for (const phase of PHASES) { const stdoutPath = path.join(evidenceDir, `mvnw-${phase}.stdout.log`), stderrPath = path.join(evidenceDir, `mvnw-${phase}.stderr.log`), startedAt = isoNow(), started = process.hrtime.bigint(); const outcome = await execute(wrapper, phase, projectRoot); const durationMs = Number(process.hrtime.bigint() - started) / 1e6; await writeText(stdoutPath, outcome.stdout); await writeText(stderrPath, outcome.stderr); commands.push({ command: `./mvnw ${phase}`, phase, exit_code: outcome.exitCode, duration_ms: Number(durationMs.toFixed(3)), started_at: startedAt, executed_at: isoNow(), stdout_ref: stdoutPath, stderr_ref: stderrPath }); }
+  return { verification_mode: "controlled-generation", project_root: projectRoot, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: commands.every((item) => item.exit_code === 0) ? "passed" : "failed", commands };
+}
+async function main() { let args; try { args = parseArgs(process.argv.slice(2)); if (args.help) { console.log("运行 YSS 脚手架真实验证命令\n用法: node scripts/run_scaffold_verification.mjs --project-root <dir> --evidence-dir <dir>"); return 0; } const reportPath = path.join(args.evidenceDir, "scaffold-verification.json"); try { const report = await run(args.projectRoot, args.evidenceDir); await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); console.log(`${report.status}: ${reportPath}`); return report.status === "passed" ? 0 : 1; } catch (error) { const report = { verification_mode: "controlled-generation", project_root: args.projectRoot, generated_at: isoNow(), status: "failed", error: error.message, commands: [] }; await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } } catch (error) { process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } }
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exitCode = await main();

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { run } from "./run_scaffold_verification.mjs";
+
+const scripts = path.dirname(fileURLToPath(import.meta.url));
+const generator = path.join(scripts, "generate_scaffold.mjs");
+const command = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [generator, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
+function contract(outputDir, overrides = {}) {
+  return { schema_version: 1, contract_id: "scaffold-1", contract_version: 1, slice_id: "slice-1", status: "approved", router_draft_ref: "router-1", lifecycle_approval_ref: "approval-1", persisted_ref: "persisted-1", current_version: 1, implementation_repository: "external", backend_repository: "external", scaffold_status: "required", target_git_url_or_output_dir: outputDir, allowed_write_paths: ["."], expected_evidence_files: [".yss/scaffold-generation.json"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], approval: { approval_ref: "approval-1", approver: "reviewer", persisted_ref: "persisted-1", current_version: 1 }, work_unit: { id: "unit-1", behavior: "scaffold", primary_skill: "yss-ddd-scaffold-generator", supporting_skills: ["yss-router"], tdd_mode: "controlled-generation", allowed_write_paths: ["."], expected_evidence: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], controlled_generation: true }, overwrite_policy: { force_allowed: true, overwrite_scope: "replace-service", rollback_ref: "checkpoint-1" }, ...overrides };
+}
+async function fixture() { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-node-")); const output = path.join(root, "implementation"); await mkdir(output); const contractFile = path.join(root, "contract.json"); await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`); return { root, output, contractFile, args: ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile] }; }
+
+test("生成批准合同下的纯工程骨架，并写入清单", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); });
+
+test("拒绝不一致合同和未经明确批准的非空目录覆盖", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const rejected = await command([...data.args.slice(0, -1), path.join(data.root, "missing.json")]); assert.equal(rejected.code, 1); assert.match(rejected.stderr, /合同/); await mkdir(path.join(data.output, "demo-service")); await writeFile(path.join(data.output, "demo-service", "keep.txt"), "keep"); const noForce = await command(data.args); assert.equal(noForce.code, 1); assert.match(noForce.stderr, /--force/); const forceMissingRollback = await command([...data.args, "--force"]); assert.equal(forceMissingRollback.code, 1); assert.match(forceMissingRollback.stderr, /覆盖范围和回滚引用/); });
+
+test("已批准的 --force 先备份非空目标，再提交 staging 工程", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const oldProject = path.join(data.output, "demo-service"); await mkdir(oldProject); await writeFile(path.join(oldProject, "old.txt"), "recoverable"); const result = await command([...data.args, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]); assert.equal(result.code, 0, result.stderr); const entries = await readdir(data.output); const backup = entries.find((entry) => entry.startsWith(".demo-service.backup-")); assert.ok(backup); assert.equal(await readFile(path.join(data.output, backup, "old.txt"), "utf8"), "recoverable"); assert.ok((await readdir(path.join(data.output, "demo-service"))).includes("pom.xml")); });
+
+test("验证器记录三条 wrapper 命令的成功和失败证据", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\n[ \"$1\" = test ] && exit 2\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const evidence = path.join(root, "evidence"); const report = await run(project, evidence); assert.equal(report.status, "failed"); assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 2, 0]); assert.match(await readFile(path.join(evidence, "mvnw-test.stderr.log"), "utf8"), /^$/); });
+
+test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence")); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });