scaffold-engine 0.1.0

package/tools/init-project.cjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { loadRuntimeConfig } = require('./lib/model-toolkit.cjs');
+
+function initProject(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const force = Boolean(options.force);
+  const withCursorRule = options.withCursorRule !== false;
+  const runtimeConfig = loadRuntimeConfig();
+
+  const configPath = path.join(projectRoot, 'scaffold.engine.json');
+  const bridgeDir = path.join(projectRoot, '.scaffold', 'bin');
+  const bridgePath = path.join(bridgeDir, 'scaffold-engine.cjs');
+  const directories = [
+    path.join(projectRoot, '.codex', 'scaffold-drafts'),
+    path.join(projectRoot, '.codex', 'generated-specs'),
+    bridgeDir,
+    path.join(projectRoot, 'src', 'generated', 'api'),
+    path.join(projectRoot, 'src', 'generated', 'admin'),
+  ];
+
+  for (const dirPath of directories) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+
+  const config = {
+    projectRoot,
+    catalogs: {
+      rootDir: runtimeConfig.catalogs.rootDir,
+    },
+    rules: {
+      rootDir: runtimeConfig.rules.rootDir,
+    },
+    drafts: {
+      rootDir: path.join(projectRoot, '.codex', 'scaffold-drafts'),
+    },
+    generatedSpecs: {
+      rootDir: path.join(projectRoot, '.codex', 'generated-specs'),
+    },
+    targets: {
+      adapter: 'external-project',
+      apiSrcDir: path.join(projectRoot, 'src', 'generated', 'api'),
+      adminSrcDir: path.join(projectRoot, 'src', 'generated', 'admin'),
+      toolCwd: runtimeConfig.scaffoldRoot,
+      pnpmCwd: path.resolve(runtimeConfig.scaffoldRoot, '..'),
+      apiPackageDir: runtimeConfig.targets.apiPackageDir,
+    },
+  };
+
+  writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, force);
+  writeFile(bridgePath, buildBridgeScript(runtimeConfig.scaffoldRoot), force);
+
+  let cursorRulePath = '';
+  if (withCursorRule) {
+    cursorRulePath = path.join(projectRoot, '.cursor', 'rules', 'scaffold-engine.mdc');
+    fs.mkdirSync(path.dirname(cursorRulePath), { recursive: true });
+    writeFile(cursorRulePath, buildCursorRule(), force);
+  }
+
+  return {
+    projectRoot,
+    configPath,
+    bridgePath,
+    directories,
+    cursorRulePath: cursorRulePath || null,
+  };
+}
+
+function writeFile(filePath, content, force) {
+  if (fs.existsSync(filePath) && !force) {
+    return;
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function buildCursorRule() {
+  return `---
+description: Automatically use scaffold-engine for business module requirements in this project.
+globs:
+alwaysApply: true
+---
+
+When the user asks for a new business object/module/system capability in this project, do not ask them to spell out tool steps.
+
+Use the local bridge command:
+
+- \`node ./.scaffold/bin/scaffold-engine.cjs ...\`
+
+Use the project config:
+
+- \`./scaffold.engine.json\`
+
+Default behavior:
+
+1. Treat a plain natural-language requirement as an engine request.
+2. First run analyze.
+3. Then create a draft automatically.
+4. If the requirement is incomplete, summarize the missing information and show the draft id.
+5. If the draft is valid enough, run:
+   - \`draft:validate\`
+   - \`draft:generate --dry-run\`
+6. Do not do real generation until the user explicitly confirms.
+
+The user should only need to say things like:
+
+- “做一个员工管理，支持新建、编辑、列表、详情”
+- “做一个组织树”
+- “做一个候选人管理，包含跟进记录”
+
+Always explain:
+
+- recognized pattern
+- candidate object
+- draft id
+- validation result
+- dry-run target paths
+`;
+}
+
+function buildBridgeScript(scaffoldRoot) {
+  const cliPath = path.join(scaffoldRoot, 'tools', 'cli.cjs');
+  const escapedCliPath = JSON.stringify(cliPath);
+  return `#!/usr/bin/env node
+const path = require('path');
+const { createRequire } = require('module');
+const { spawnSync } = require('child_process');
+
+const projectRoot = path.resolve(__dirname, '..', '..');
+const configPath = path.join(projectRoot, 'scaffold.engine.json');
+const fallbackCliPath = ${escapedCliPath};
+const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+
+let cliPath = fallbackCliPath;
+try {
+  cliPath = projectRequire.resolve('scaffold-engine/cli');
+} catch (error) {
+  cliPath = fallbackCliPath;
+}
+
+const args = process.argv.slice(2);
+const hasConfig = args.includes('--config');
+const nextArgs = hasConfig ? args : [...args, '--config', configPath];
+
+const result = spawnSync(process.execPath, [cliPath, ...nextArgs], {
+  cwd: projectRoot,
+  stdio: 'inherit',
+});
+
+process.exit(result.status ?? 1);
+`;
+}
+
+function parseArgs(argv) {
+  const options = {
+    projectRoot: '',
+    force: false,
+    withCursorRule: true,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (item === '--project-root') {
+      options.projectRoot = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (item === '--force') {
+      options.force = true;
+      continue;
+    }
+    if (item === '--no-cursor-rule') {
+      options.withCursorRule = false;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+if (require.main === module) {
+  try {
+    const result = initProject(parseArgs(process.argv.slice(2)));
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error(`\n❌ 项目初始化失败: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  initProject,
+  parseArgs,
+};

package/tools/lib/draft-toolkit.cjs

@@ -0,0 +1,357 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const YAML = require('yaml');
+const { loadRuntimeConfig, readJson, resolveScaffoldPath, validateModelFile } = require('./model-toolkit.cjs');
+const { resolveDraftRoot, resolveRulePath } = require('./runtime-config.cjs');
+
+function createDraft(requirement, analysis) {
+  const now = new Date().toISOString();
+  const decision = analysis?.decision || 'need_more_info';
+  return {
+    contractVersion: '1.0.0',
+    kind: 'requirementDraft',
+    id: buildDraftId(),
+    status: mapDraftStatus(decision),
+    rawRequirement: requirement,
+    analysis,
+    draftModel: analysis?.suggestedModel || null,
+    validation: null,
+    generation: null,
+    storage: null,
+    history: [
+      {
+        event: 'draft.created',
+        timestamp: now,
+        summary: `由 analyze 结果创建草稿，decision=${decision}`,
+      },
+    ],
+  };
+}
+
+function patchDraft(draft, patch) {
+  const now = new Date().toISOString();
+  const nextDraftModel = deepMerge(draft.draftModel || {}, patch || {});
+  return {
+    ...draft,
+    status: 'clarifying',
+    draftModel: nextDraftModel,
+    validation: null,
+    generation: null,
+    storage: draft.storage || null,
+    history: [
+      ...(draft.history || []),
+      {
+        event: 'draft.patched',
+        timestamp: now,
+        summary: buildPatchSummary(patch),
+      },
+    ],
+  };
+}
+
+function validateDraft(draft, options = {}) {
+  if (!draft?.draftModel) {
+    throw new Error('草稿中不存在 draftModel，无法执行校验');
+  }
+
+  const runtimeConfig = loadRuntimeConfig(options);
+  const result = withTempSpec(draft.draftModel, (specPath) => validateModelFile(specPath, runtimeConfig));
+  const report = buildDraftValidationReport(result);
+  return {
+    ...draft,
+    status: report.status === 'passed' ? 'validated' : 'clarifying',
+    validation: report,
+    storage: draft.storage || null,
+    history: [
+      ...(draft.history || []),
+      {
+        event: 'draft.validated',
+        timestamp: new Date().toISOString(),
+        summary: `执行草稿校验，status=${report.status}`,
+      },
+    ],
+  };
+}
+
+function generateDraft(draft, options = {}) {
+  if (!draft?.draftModel) {
+    throw new Error('草稿中不存在 draftModel，无法执行生成');
+  }
+
+  const runtimeConfig = loadRuntimeConfig(options);
+  const validatedDraft = validateDraft(draft, runtimeConfig);
+  if (validatedDraft.validation?.status !== 'passed') {
+    throw new Error('草稿校验未通过，无法执行生成');
+  }
+
+  const result = withTempSpec(draft.draftModel, (specPath) => {
+    const args = [path.join(resolveScaffoldPath('tools'), 'generate-module.cjs'), specPath];
+    if (options.force !== false) {
+      args.push('--force');
+    }
+    if (options.dryRun) {
+      args.push('--dry-run');
+    }
+    if (options.configPath) {
+      args.push('--config', path.resolve(options.configPath));
+    }
+
+    return spawnSync(process.execPath, args, {
+      cwd: runtimeConfig.targets.toolCwd,
+      encoding: 'utf8',
+    });
+  });
+
+  if (result.status !== 0) {
+    throw new Error(result.stderr || result.stdout || '草稿生成失败');
+  }
+
+  const generatedFiles = String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('- ['))
+    .map((line) => line.replace(/^- \[[^\]]+\]\s+/, ''));
+
+  return {
+    ...validatedDraft,
+    status: 'generated',
+    generation: {
+      contractVersion: '1.0.0',
+      stage: 'generateDraft',
+      status: 'passed',
+      generatedFiles,
+      dryRun: Boolean(options.dryRun),
+    },
+    storage: validatedDraft.storage || null,
+    history: [
+      ...(validatedDraft.history || []),
+      {
+        event: 'draft.generated',
+        timestamp: new Date().toISOString(),
+        summary: `执行草稿生成，files=${generatedFiles.length}`,
+      },
+    ],
+  };
+}
+
+function buildDraftId() {
+  return `draft_${crypto.randomBytes(6).toString('hex')}`;
+}
+
+function getDefaultDraftRoot() {
+  return resolveDraftRoot(loadRuntimeConfig());
+}
+
+function saveDraft(draft, options = {}) {
+  if (!draft || !draft.id) {
+    throw new Error('保存 draft 失败：缺少有效 draft.id');
+  }
+
+  const draftRoot = path.resolve(options.draftRoot || getDefaultDraftRoot());
+  fs.mkdirSync(draftRoot, { recursive: true });
+
+  const fileName = options.fileName || buildDraftFileName(draft);
+  const absolutePath = path.join(draftRoot, fileName);
+  const nextDraft = {
+    ...draft,
+    storage: {
+      draftRoot,
+      fileName,
+      absolutePath,
+      savedAt: new Date().toISOString(),
+    },
+  };
+
+  fs.writeFileSync(absolutePath, `${JSON.stringify(nextDraft, null, 2)}\n`, 'utf8');
+  return nextDraft;
+}
+
+function loadDraft(reference, options = {}) {
+  const absolutePath = resolveDraftReference(reference, options);
+  return JSON.parse(fs.readFileSync(absolutePath, 'utf8'));
+}
+
+function resolveDraftReference(reference, options = {}) {
+  if (!reference || !String(reference).trim()) {
+    throw new Error('请提供 draft 引用，可以是 draft 路径或 draft id');
+  }
+
+  const value = String(reference).trim();
+  if (fs.existsSync(value) && fs.statSync(value).isFile()) {
+    return path.resolve(value);
+  }
+
+  if (value.includes(path.sep) || value.endsWith('.json')) {
+    const absolutePath = path.resolve(value);
+    if (!fs.existsSync(absolutePath)) {
+      throw new Error(`未找到 draft 文件: ${absolutePath}`);
+    }
+    return absolutePath;
+  }
+
+  const draftRoot = path.resolve(options.draftRoot || getDefaultDraftRoot());
+  if (!fs.existsSync(draftRoot)) {
+    throw new Error(`未找到 draft 目录: ${draftRoot}`);
+  }
+
+  const directPath = path.join(draftRoot, value);
+  if (fs.existsSync(directPath) && fs.statSync(directPath).isFile()) {
+    return directPath;
+  }
+
+  const directJsonPath = path.join(draftRoot, `${value}.json`);
+  if (fs.existsSync(directJsonPath) && fs.statSync(directJsonPath).isFile()) {
+    return directJsonPath;
+  }
+
+  const matches = fs
+    .readdirSync(draftRoot)
+    .filter((fileName) => fileName.startsWith(value) && fileName.endsWith('.json'))
+    .sort();
+
+  if (matches.length === 1) {
+    return path.join(draftRoot, matches[0]);
+  }
+  if (matches.length > 1) {
+    throw new Error(`找到多个匹配的 draft，请改用完整路径或文件名: ${matches.join(', ')}`);
+  }
+
+  throw new Error(`未找到 draft 引用: ${value}`);
+}
+
+function mapDraftStatus(decision) {
+  switch (decision) {
+    case 'extendable':
+      return 'analyzed';
+    case 'need_more_info':
+      return 'clarifying';
+    default:
+      return 'failed';
+  }
+}
+
+function loadDraftSchema() {
+  const runtimeConfig = loadRuntimeConfig();
+  return readJson(resolveRulePath(runtimeConfig, 'requirementDraftSchema'));
+}
+
+function buildDraftFileName(draft) {
+  const slug = slugifyDraft(draft);
+  return `${draft.id}--${slug}.json`;
+}
+
+function withTempSpec(model, runner) {
+  const tempPath = path.join(
+    os.tmpdir(),
+    `scaffold-draft-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.yaml`
+  );
+  fs.writeFileSync(tempPath, YAML.stringify(model), 'utf8');
+  try {
+    return runner(tempPath);
+  } finally {
+    if (fs.existsSync(tempPath)) {
+      fs.rmSync(tempPath, { force: true });
+    }
+  }
+}
+
+function buildDraftValidationReport(result) {
+  const schemaErrors = result.schemaErrors || [];
+  const boundaryErrors = result.boundaryErrors || [];
+  const governanceErrors = result.governanceErrors || [];
+  const warnings = result.warnings || [];
+  return {
+    contractVersion: '1.0.0',
+    stage: 'validateDraft',
+    status: result.valid ? 'passed' : 'failed',
+    nextAction: result.valid ? 'generate' : 'clarify',
+    scope: result.location?.scope || 'temporaryDraft',
+    object: {
+      domain: result.model?.meta?.domain || '',
+      object: result.model?.meta?.object || '',
+      label: result.model?.meta?.label || '',
+      pattern: result.model?.meta?.pattern || '',
+    },
+    stages: [
+      { stage: 'schema', status: schemaErrors.length === 0 ? 'passed' : 'failed', errors: schemaErrors },
+      { stage: 'boundary', status: boundaryErrors.length === 0 ? 'passed' : 'failed', errors: boundaryErrors },
+      { stage: 'governance', status: governanceErrors.length === 0 ? 'passed' : 'failed', errors: governanceErrors },
+    ],
+    errors: [
+      ...schemaErrors.map((message) => ({ stage: 'schema', message })),
+      ...boundaryErrors.map((message) => ({ stage: 'boundary', message })),
+      ...governanceErrors.map((message) => ({ stage: 'governance', message })),
+    ],
+    warnings,
+  };
+}
+
+function deepMerge(base, patch) {
+  if (Array.isArray(patch)) {
+    return patch.map((item) => cloneValue(item));
+  }
+  if (!isObject(base) || !isObject(patch)) {
+    return cloneValue(patch);
+  }
+
+  const next = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (Array.isArray(value)) {
+      next[key] = value.map((item) => cloneValue(item));
+      continue;
+    }
+    if (isObject(value) && isObject(base[key])) {
+      next[key] = deepMerge(base[key], value);
+      continue;
+    }
+    next[key] = cloneValue(value);
+  }
+  return next;
+}
+
+function cloneValue(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function isObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function buildPatchSummary(patch) {
+  if (!patch || !isObject(patch)) {
+    return '未提供有效 patch，草稿未变更';
+  }
+  return `更新草稿片段: ${Object.keys(patch).join(', ')}`;
+}
+
+function slugifyDraft(draft) {
+  const rawValue =
+    draft?.draftModel?.meta?.object ||
+    draft?.analysis?.candidate?.object ||
+    draft?.analysis?.inferred?.object ||
+    draft?.analysis?.candidate?.label ||
+    'draft';
+  const normalized = String(rawValue)
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  return normalized || 'draft';
+}
+
+module.exports = {
+  createDraft,
+  generateDraft,
+  getDefaultDraftRoot,
+  loadDraft,
+  loadDraftSchema,
+  patchDraft,
+  resolveDraftReference,
+  saveDraft,
+  validateDraft,
+};