kiro-spec-engine 1.38.0 → 1.40.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.40.0] - 2026-02-10
+
+### Added
+- **Moqui Scene Template Extractor**: Extract reusable scene templates from live Moqui ERP instances
+  - `MoquiExtractor` — Analyze discovered Moqui resources, identify business patterns (crud/query/workflow), generate scene template bundles
+  - Built-in YAML serializer for scene manifests (`kse.scene/v0.2` apiVersion)
+  - Entity grouping by Header/Item suffix patterns (e.g., OrderHeader + OrderItem → composite pattern)
+  - Pattern-based manifest generation with governance contracts (risk_level, approval, idempotency)
+  - Package contract generation (`kse.scene.package/v0.1` apiVersion) with template parameters
+  - Template bundle file writing with partial failure resilience
+  - `kse scene extract` — Extract scene templates from Moqui ERP instance
+    - `--config <path>` custom adapter config path
+    - `--type <type>` filter discovery by resource type (entities|services|screens)
+    - `--pattern <pattern>` filter by business pattern (crud|query|workflow)
+    - `--out <dir>` output directory for template bundles
+    - `--dry-run` preview extraction without writing files
+    - `--json` structured JSON output
+
+### Fixed
+- **scene discover**: Fixed `response.body.data` → `response.data` property access for Moqui catalog endpoint responses
+
+## [1.39.0] - 2026-02-10
+
+### Added
+- **Moqui ERP Adapter**: Integrate Moqui ERP instance into KSE scene runtime
+  - `MoquiClient` — HTTP client with JWT auth lifecycle (login, refresh, re-login, logout), retry logic using Node.js built-in `http`/`https`
+  - `MoquiAdapter` — Binding handler for `spec.erp.*` and `moqui.*` refs, entity CRUD, service invocation, screen discovery
+  - `kse scene connect` — Test connectivity and authentication to Moqui ERP instance
+    - `--config <path>` custom adapter config path
+    - `--json` structured JSON output
+  - `kse scene discover` — Discover available entities, services, and screens from Moqui ERP
+    - `--config <path>` custom adapter config path
+    - `--type <type>` filter by catalog type (entities|services|screens)
+    - `--json` structured JSON output
+
+### Fixed
+- **Jest forceExit**: Added `forceExit: true` to jest configs to prevent CI hang from leaked worker processes
+
 ## [1.38.0] - 2026-02-10
 
 ### Added

package/README.md

@@ -310,6 +310,15 @@ Structure your work with Requirements → Design → Tasks workflow
 - **Cross-Platform**: Consistent path handling across Windows/Linux/macOS
 - **Smart Exclusions**: Automatically skip common non-repository directories (node_modules, build, etc.)
 
+### Moqui ERP Integration 🚀 NEW in v1.39.0
+- **Moqui ERP Adapter**: Connect KSE scene runtime to live Moqui ERP instances
+  - `MoquiClient` — HTTP client with JWT auth lifecycle (login, refresh, re-login, logout) and retry logic
+  - `MoquiAdapter` — Binding handler for `spec.erp.*` and `moqui.*` refs, entity CRUD, service invocation, screen discovery
+- **Scene Template Extractor** (v1.40.0): Analyze Moqui resources, identify business patterns, generate reusable scene templates
+  - Entity grouping by Header/Item suffix patterns (e.g., OrderHeader + OrderItem → composite)
+  - Pattern-based manifest generation with governance contracts
+- **CLI Commands**: `scene connect`, `scene discover`, `scene extract` with `--json` support
+
 ### Scene Template Engine 🚀 NEW in v1.25.0
 - **Template Variable Schema**: Define typed variables (string, number, boolean, enum, array) with validation rules in scene-package.json
 - **Multi-File Rendering**: Recursive template processing with `{{variable}}` substitution, `{{#if}}` conditionals, `{{#each}}` loops
@@ -437,6 +446,11 @@ kse scene template-validate --package <path>   # Validate template variable sche
 kse scene template-resolve --package <name>    # Resolve inheritance chain and merged schema
 kse scene template-render --package <name> --values <json> --out <dir>  # Render template files
 
+# Moqui ERP integration (NEW in v1.39.0)
+kse scene connect --config <path>              # Test connectivity to Moqui ERP instance
+kse scene discover --config <path>             # Discover entities, services, screens from Moqui
+kse scene extract --config <path> --out <dir>  # Extract scene templates from Moqui (v1.40.0)
+
 # DevOps operations
 kse ops init <project-name>        # Initialize operations specs
 kse ops validate [<project>]       # Validate operations completeness

package/README.zh.md

@@ -266,6 +266,15 @@ sequenceDiagram
 - **命令执行**：在特定环境上下文中运行命令
 - **跨平台**：在 Windows、Linux 和 macOS 上无缝工作
 
+### Moqui ERP 集成 🚀 v1.39.0 新增
+- **Moqui ERP 适配器**: 将 KSE 场景运行时连接到 Moqui ERP 实例
+  - `MoquiClient` — 支持 JWT 认证生命周期（登录、刷新、重登录、登出）和重试逻辑的 HTTP 客户端
+  - `MoquiAdapter` — 处理 `spec.erp.*` 和 `moqui.*` 引用的绑定处理器，支持实体 CRUD、服务调用、屏幕发现
+- **场景模板提取器**（v1.40.0）: 分析 Moqui 资源，识别业务模式，生成可复用场景模板
+  - 按 Header/Item 后缀模式分组实体（如 OrderHeader + OrderItem → 复合模式）
+  - 基于模式的清单生成，包含治理合约
+- **CLI 命令**: `scene connect`、`scene discover`、`scene extract`，支持 `--json` 输出
+
 ### 场景模板引擎 🚀 v1.25.0 新增
 - **模板变量 Schema**: 在 scene-package.json 中定义类型化变量（string, number, boolean, enum, array）及验证规则
 - **多文件渲染**: 递归模板处理，支持 `{{variable}}` 替换、`{{#if}}` 条件、`{{#each}}` 循环
@@ -341,6 +350,11 @@ kse scene template-validate --package <path>   # 验证模板变量 schema
 kse scene template-resolve --package <name>    # 解析继承链和合并 schema
 kse scene template-render --package <name> --values <json> --out <dir>  # 渲染模板文件
 
+# Moqui ERP 集成 (v1.39.0 新增)
+kse scene connect --config <path>              # 测试 Moqui ERP 实例连接
+kse scene discover --config <path>             # 发现 Moqui 实体、服务、屏幕
+kse scene extract --config <path> --out <dir>  # 从 Moqui 提取场景模板 (v1.40.0)
+
 # DevOps 运维
 kse ops init <project-name>        # 初始化运维 specs
 kse ops validate [<project>]       # 验证运维完整性

package/docs/command-reference.md

@@ -214,6 +214,23 @@ kse scene template-render --package <name> --values <json-or-path> --out <dir>
 kse scene template-render --package scene-erp --values '{"entity_name":"Order"}' --out ./output --json
 ```
 
+### Moqui ERP Integration
+
+```bash
+# Test connectivity and authentication to Moqui ERP instance
+kse scene connect --config <path>
+kse scene connect --config ./moqui-config.json --json
+
+# Discover available entities, services, and screens from Moqui ERP
+kse scene discover --config <path>
+kse scene discover --config ./moqui-config.json --type entities --json
+
+# Extract scene templates from Moqui ERP instance
+kse scene extract --config <path> --out <dir>
+kse scene extract --config ./moqui-config.json --type entities --pattern crud --out ./templates --json
+kse scene extract --config ./moqui-config.json --dry-run --json
+```
+
 ### Version & Upgrade
 
 ```bash

package/lib/commands/scene.js

@@ -11,6 +11,9 @@ const PlanCompiler = require('../scene-runtime/plan-compiler');
 const PolicyGate = require('../scene-runtime/policy-gate');
 const RuntimeExecutor = require('../scene-runtime/runtime-executor');
 const EvalBridge = require('../scene-runtime/eval-bridge');
+const MoquiClient = require('../scene-runtime/moqui-client');
+const { loadAdapterConfig, validateAdapterConfig } = require('../scene-runtime/moqui-adapter');
+const { runExtraction, SUPPORTED_PATTERNS: EXTRACTOR_SUPPORTED_PATTERNS } = require('../scene-runtime/moqui-extractor');
 
 const RUN_MODES = new Set(['dry_run', 'commit']);
 const SCAFFOLD_TYPES = new Set(['erp', 'hybrid']);
@@ -728,6 +731,42 @@ function registerSceneCommands(program) {
     .action(async (options) => {
       await runSceneLockCommand({ ...options, action: 'ls' });
     });
+
+  // ── scene connect ──
+  sceneCmd
+    .command('connect')
+    .description('Test connectivity and authentication to a Moqui ERP instance')
+    .option('-c, --config <path>', 'Path to moqui-adapter.json config file')
+    .option('-r, --registry <path>', 'Registry root directory', '.kiro/registry')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneConnectCommand(options);
+    });
+
+  // ── scene discover ──
+  sceneCmd
+    .command('discover')
+    .description('Discover available entities, services, and screens from Moqui ERP')
+    .option('-c, --config <path>', 'Path to moqui-adapter.json config file')
+    .option('-t, --type <type>', 'Catalog type to discover (entities|services|screens)')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneDiscoverCommand(options);
+    });
+
+  // ── scene extract ──
+  sceneCmd
+    .command('extract')
+    .description('Extract scene templates from a Moqui ERP instance')
+    .option('-c, --config <path>', 'Path to moqui-adapter.json config file')
+    .option('-t, --type <type>', 'Resource type filter (entities|services|screens)')
+    .option('-p, --pattern <pattern>', 'Pattern filter (crud|query|workflow)')
+    .option('-o, --out <dir>', 'Output directory for template bundles')
+    .option('--dry-run', 'Preview extraction without writing files')
+    .option('--json', 'Print result as JSON')
+    .action(async (options) => {
+      await runSceneExtractCommand(options);
+    });
 }
 
 function normalizeSourceOptions(options = {}) {
@@ -11993,6 +12032,334 @@ function printSceneLockSummary(options, payload) {
   }
 }
 
+// ── Scene Connect ─────────────────────────────────────────────────────────
+
+function normalizeSceneConnectOptions(options = {}) {
+  return {
+    config: options.config ? String(options.config).trim() : undefined,
+    registry: options.registry ? String(options.registry).trim() : '.kiro/registry',
+    json: options.json === true
+  };
+}
+
+function validateSceneConnectOptions(options) {
+  return null;
+}
+
+async function runSceneConnectCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneConnectOptions(rawOptions);
+  const validationError = validateSceneConnectOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene connect failed: ${validationError}`));
+    process.exitCode = 1;
+    return null;
+  }
+
+  let client = null;
+  try {
+    const configResult = loadAdapterConfig(options.config, projectRoot);
+    if (configResult.error) {
+      throw new Error(configResult.error);
+    }
+
+    const validation = validateAdapterConfig(configResult.config);
+    if (!validation.valid) {
+      throw new Error(`config validation failed: ${validation.errors.join(', ')}`);
+    }
+
+    const config = configResult.config;
+    client = new MoquiClient(config);
+    const loginResult = await client.login();
+
+    let payload;
+    if (loginResult.success) {
+      payload = {
+        success: true,
+        baseUrl: config.baseUrl,
+        authStatus: 'authenticated'
+      };
+    } else {
+      payload = {
+        success: false,
+        baseUrl: config.baseUrl,
+        error: { code: 'AUTH_FAILED', message: loginResult.error || 'authentication failed' }
+      };
+    }
+
+    printSceneConnectSummary(options, payload);
+    return payload;
+  } catch (error) {
+    const payload = {
+      success: false,
+      baseUrl: rawOptions.config || 'unknown',
+      error: { code: 'CONNECT_FAILED', message: error.message }
+    };
+    printSceneConnectSummary(options, payload);
+    process.exitCode = 1;
+    return payload;
+  } finally {
+    if (client) {
+      try { await client.dispose(); } catch (_) { /* ignore dispose errors */ }
+    }
+  }
+}
+
+function printSceneConnectSummary(options, payload) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.success) {
+    console.log(chalk.green(`Connected to Moqui ERP at ${payload.baseUrl}`));
+    console.log(`  Auth status: ${payload.authStatus}`);
+  } else {
+    console.error(chalk.red(`Connection failed: ${payload.error.message}`));
+    if (payload.baseUrl && payload.baseUrl !== 'unknown') {
+      console.error(`  Target: ${payload.baseUrl}`);
+    }
+  }
+}
+
+// ── Scene Discover ────────────────────────────────────────────────────────
+
+function normalizeSceneDiscoverOptions(options = {}) {
+  return {
+    config: options.config ? String(options.config).trim() : undefined,
+    type: options.type ? String(options.type).trim() : undefined,
+    json: options.json === true
+  };
+}
+
+function validateSceneDiscoverOptions(options) {
+  if (options.type && !['entities', 'services', 'screens'].includes(options.type)) {
+    return `invalid --type "${options.type}", must be entities, services, or screens`;
+  }
+  return null;
+}
+
+async function runSceneDiscoverCommand(rawOptions = {}, dependencies = {}) {
+  const projectRoot = dependencies.projectRoot || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+
+  const options = normalizeSceneDiscoverOptions(rawOptions);
+  const validationError = validateSceneDiscoverOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(`Scene discover failed: ${validationError}`));
+    process.exitCode = 1;
+    return null;
+  }
+
+  let client = null;
+  try {
+    const configResult = loadAdapterConfig(options.config, projectRoot);
+    if (configResult.error) {
+      throw new Error(configResult.error);
+    }
+
+    const validation = validateAdapterConfig(configResult.config);
+    if (!validation.valid) {
+      throw new Error(`config validation failed: ${validation.errors.join(', ')}`);
+    }
+
+    const config = configResult.config;
+    client = new MoquiClient(config);
+    const loginResult = await client.login();
+
+    if (!loginResult.success) {
+      throw new Error(loginResult.error || 'authentication failed');
+    }
+
+    let payload;
+
+    if (options.type) {
+      // Query specific catalog type
+      const endpoint = options.type === 'entities'
+        ? '/api/v1/entities'
+        : options.type === 'services'
+          ? '/api/v1/services'
+          : '/api/v1/screens';
+
+      const response = await client.request('GET', endpoint);
+      const rawData = (response && response.data) || {};
+      const items = Array.isArray(rawData) ? rawData : (rawData[options.type] || rawData.items || []);
+      payload = {
+        success: true,
+        type: options.type,
+        [options.type]: Array.isArray(items) ? items : [],
+        count: Array.isArray(items) ? items.length : 0
+      };
+    } else {
+      // Query all catalog types for summary
+      const [entitiesRes, servicesRes, screensRes] = await Promise.all([
+        client.request('GET', '/api/v1/entities').catch(() => null),
+        client.request('GET', '/api/v1/services').catch(() => null),
+        client.request('GET', '/api/v1/screens').catch(() => null)
+      ]);
+
+      const entitiesRaw = (entitiesRes && entitiesRes.data) || {};
+      const servicesRaw = (servicesRes && servicesRes.data) || {};
+      const screensRaw = (screensRes && screensRes.data) || {};
+      const entitiesData = Array.isArray(entitiesRaw) ? entitiesRaw : (entitiesRaw.entities || entitiesRaw.items || []);
+      const servicesData = Array.isArray(servicesRaw) ? servicesRaw : (servicesRaw.services || servicesRaw.items || []);
+      const screensData = Array.isArray(screensRaw) ? screensRaw : (screensRaw.screens || screensRaw.items || []);
+
+      payload = {
+        success: true,
+        summary: {
+          entities: { count: Array.isArray(entitiesData) ? entitiesData.length : 0 },
+          services: { count: Array.isArray(servicesData) ? servicesData.length : 0 },
+          screens: { count: Array.isArray(screensData) ? screensData.length : 0 }
+        }
+      };
+    }
+
+    printSceneDiscoverSummary(options, payload);
+    return payload;
+  } catch (error) {
+    const payload = {
+      success: false,
+      error: { code: 'DISCOVER_FAILED', message: error.message }
+    };
+    printSceneDiscoverSummary(options, payload);
+    process.exitCode = 1;
+    return payload;
+  } finally {
+    if (client) {
+      try { await client.dispose(); } catch (_) { /* ignore dispose errors */ }
+    }
+  }
+}
+
+function printSceneDiscoverSummary(options, payload) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (!payload.success) {
+    console.error(chalk.red(`Discovery failed: ${payload.error.message}`));
+    return;
+  }
+
+  if (payload.summary) {
+    console.log(chalk.green('Moqui ERP catalog summary:'));
+    console.log(`  Entities: ${payload.summary.entities.count}`);
+    console.log(`  Services: ${payload.summary.services.count}`);
+    console.log(`  Screens:  ${payload.summary.screens.count}`);
+  } else {
+    console.log(chalk.green(`Discovered ${payload.count} ${payload.type}:`));
+    const items = payload[payload.type] || [];
+    for (const item of items.slice(0, 50)) {
+      const name = typeof item === 'string' ? item : (item.name || item.entityName || JSON.stringify(item));
+      console.log(`  ${name}`);
+    }
+    if (items.length > 50) {
+      console.log(`  ... and ${items.length - 50} more`);
+    }
+  }
+}
+
+// ─── Scene Extract CLI Functions ──────────────────────────────────
+
+function normalizeSceneExtractOptions(options = {}) {
+  return {
+    config: options.config ? String(options.config).trim() : undefined,
+    type: options.type ? String(options.type).trim() : undefined,
+    pattern: options.pattern ? String(options.pattern).trim() : undefined,
+    out: options.out ? String(options.out).trim() : '.kiro/templates/extracted',
+    dryRun: options.dryRun === true,
+    json: options.json === true
+  };
+}
+
+function validateSceneExtractOptions(options) {
+  if (options.type && !['entities', 'services', 'screens'].includes(options.type)) {
+    return `invalid --type "${options.type}", must be entities, services, or screens`;
+  }
+  if (options.pattern && !EXTRACTOR_SUPPORTED_PATTERNS.includes(options.pattern)) {
+    return `invalid --pattern "${options.pattern}", must be one of: ${EXTRACTOR_SUPPORTED_PATTERNS.join(', ')}`;
+  }
+  return null;
+}
+
+function printSceneExtractSummary(options, payload) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (!payload.success) {
+    console.error(chalk.red(`Extraction failed: ${payload.error.message}`));
+    return;
+  }
+
+  const summary = payload.summary || {};
+  const patterns = summary.patterns || {};
+
+  console.log(chalk.green(`Extracted ${summary.totalTemplates || 0} template(s):`));
+  console.log(`  CRUD:     ${patterns.crud || 0}`);
+  console.log(`  Query:    ${patterns.query || 0}`);
+  console.log(`  Workflow: ${patterns.workflow || 0}`);
+
+  if (options.dryRun) {
+    console.log(chalk.yellow('  (dry-run — no files written)'));
+  } else {
+    console.log(`  Output:   ${summary.outputDir || options.out}`);
+  }
+
+  if (payload.warnings && payload.warnings.length > 0) {
+    console.log(chalk.yellow(`  Warnings: ${payload.warnings.length}`));
+    for (const w of payload.warnings) {
+      console.log(chalk.yellow(`    - ${w}`));
+    }
+  }
+}
+
+async function runSceneExtractCommand(rawOptions = {}, dependencies = {}) {
+  const options = normalizeSceneExtractOptions(rawOptions);
+  const validationError = validateSceneExtractOptions(options);
+
+  if (validationError) {
+    console.error(chalk.red(validationError));
+    process.exitCode = 1;
+    return null;
+  }
+
+  try {
+    const payload = await runExtraction({
+      config: options.config,
+      type: options.type,
+      pattern: options.pattern,
+      out: options.out,
+      dryRun: options.dryRun
+    }, dependencies);
+
+    if (!payload.success) {
+      process.exitCode = 1;
+    }
+
+    printSceneExtractSummary(options, payload);
+    return payload;
+  } catch (error) {
+    const payload = {
+      success: false,
+      templates: [],
+      summary: { totalTemplates: 0, patterns: { crud: 0, query: 0, workflow: 0 }, outputDir: options.out },
+      warnings: [],
+      error: { code: 'EXTRACT_FAILED', message: error.message }
+    };
+    printSceneExtractSummary(options, payload);
+    process.exitCode = 1;
+    return payload;
+  }
+}
+
 module.exports = {
   RUN_MODES,
   SCAFFOLD_TYPES,
@@ -12185,5 +12552,17 @@ module.exports = {
   normalizeSceneLockOptions,
   validateSceneLockOptions,
   runSceneLockCommand,
-  printSceneLockSummary
+  printSceneLockSummary,
+  normalizeSceneConnectOptions,
+  validateSceneConnectOptions,
+  runSceneConnectCommand,
+  printSceneConnectSummary,
+  normalizeSceneDiscoverOptions,
+  validateSceneDiscoverOptions,
+  runSceneDiscoverCommand,
+  printSceneDiscoverSummary,
+  normalizeSceneExtractOptions,
+  validateSceneExtractOptions,
+  runSceneExtractCommand,
+  printSceneExtractSummary
 };