@miniidealab/openlogos 0.5.9 → 0.6.0

package/dist/lib/json-output.js

@@ -0,0 +1,25 @@
+export const VERSION = '0.6.0';
+export function parseFormat(args) {
+    const idx = args.indexOf('--format');
+    if (idx !== -1 && args[idx + 1] === 'json') {
+        return 'json';
+    }
+    return 'text';
+}
+export function makeEnvelope(command, data) {
+    return {
+        command,
+        version: VERSION,
+        timestamp: new Date().toISOString(),
+        data,
+    };
+}
+export function makeErrorEnvelope(command, code, message) {
+    return {
+        command,
+        version: VERSION,
+        timestamp: new Date().toISOString(),
+        error: { code, message },
+    };
+}
+//# sourceMappingURL=json-output.js.map

package/dist/lib/json-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-output.js","sourceRoot":"","sources":["../../src/lib/json-output.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAI/B,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAaD,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAa;IACzD,OAAO;QACL,OAAO;QACP,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,IAAI;KACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,IAAY,EAAE,OAAe;IAC9E,OAAO;QACL,OAAO;QACP,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;KACzB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miniidealab/openlogos",
-  "version": "0.5.9",
+  "version": "0.6.0",
   "description": "CLI tool for the OpenLogos software engineering methodology",
   "type": "module",
   "bin": {

package/skills/code-implementor/SKILL.en.md

@@ -54,12 +54,14 @@ test-writer writes no code; code-implementor designs no test cases; code-reviewe
 | Test case specs | `logos/resources/test/*-test-cases.md` | Verification targets — UT/ST IDs, expected inputs/outputs |
 | Orchestration tests | `logos/resources/scenario/*.json` | End-to-end verification targets (API projects) |
 | Project config | `logos/logos-project.yaml` | `tech_stack`, `external_dependencies` |
+| Source roots | `logos/logos.config.json` → `sourceRoots` | Output root directories for business code and test code |
 
 After loading, confirm:
 - Which scenarios are in scope (S01, S02...)
 - Which API endpoints and DB tables are involved
 - Total UT/ST case count
 - Technology stack confirmation (language, framework, test framework)
+- Source output directories confirmed (read `sourceRoots.src` and `sourceRoots.test`; default to `src/` and `test/` if absent)
 
 ### Step 2: Plan Batch Strategy
 
@@ -163,16 +165,18 @@ After each batch:
 1. **Prompt to run tests**: Tell the user the test command (e.g., `npm test`, `pytest`)
 2. **Prompt to check results**: Confirm `logos/resources/verify/test-results.jsonl` was generated
 3. **After all batches complete**: Guide the user to run `openlogos verify` for Gate 3.5 acceptance
+4. **Update sourceRoots**: If the actual source directories differ from `sourceRoots` in `logos.config.json`, update the config to reflect the real paths. For example, if business code is placed in `app/` instead of the default `src/`, update `sourceRoots.src` to `["app"]`
+5. **Write implementation manifest**: Create an implementation manifest file in `logos/resources/implementation/` (e.g., `implementation-manifest.md`) recording the scenarios, endpoints, and case IDs covered, marking Phase 3-4 as complete
 
 If the user wants a quality audit, suggest using the `code-reviewer` Skill.
 
 ## Output Specification
 
-- **Business code**: Output to the project source tree (directory structure follows architecture design conventions)
-- **Test code**: Output to the project test directory
+- **Business code**: Output to the directories specified by `sourceRoots.src` (default `src/`, as configured in `logos.config.json`)
+- **Test code**: Output to the directories specified by `sourceRoots.test` (default `test/`, as configured in `logos.config.json`)
 - **Reporter**: Embedded in test code (not a standalone file)
 - **JSONL results**: `logos/resources/verify/test-results.jsonl`
-- This Skill does not produce files under `logos/resources/` (code goes to the project source tree; JSONL is produced at test runtime)
+- **Implementation manifest**: `logos/resources/implementation/implementation-manifest.md` (created after all batches complete)
 
 ## Best Practices
 

package/skills/code-implementor/SKILL.md

@@ -54,12 +54,14 @@ test-writer 不写代码；code-implementor 不设计用例；code-reviewer 不
 | 测试用例规格 | `logos/resources/test/*-test-cases.md` | 验证目标——UT/ST ID、预期输入输出 |
 | 编排测试 | `logos/resources/scenario/*.json` | 端到端验证目标（API 项目） |
 | 项目配置 | `logos/logos-project.yaml` | `tech_stack`、`external_dependencies` |
+| 源码位置 | `logos/logos.config.json` → `sourceRoots` | 业务代码和测试代码的输出根目录 |
 
 读取完成后，确认以下信息：
 - 本次实现涉及哪些场景（S01、S02...）
 - 涉及哪些 API 端点和 DB 表
 - 对应的 UT/ST 用例总数
 - 技术栈确认（语言、框架、测试框架）
+- 源码输出目录确认（读取 `sourceRoots.src` 和 `sourceRoots.test`，若不存在则默认 `src/` 和 `test/`）
 
 ### Step 2: 规划分批策略
 
@@ -163,16 +165,18 @@ test-writer 不写代码；code-implementor 不设计用例；code-reviewer 不
 1. **提示运行测试**：告诉用户运行测试命令（如 `npm test`、`pytest`）
 2. **提示检查结果**：确认 `logos/resources/verify/test-results.jsonl` 已生成
 3. **所有批次完成后**：引导用户运行 `openlogos verify` 执行 Gate 3.5 验收
+4. **更新 sourceRoots**：如果实际使用的源码目录与 `logos.config.json` 中的 `sourceRoots` 不同，更新配置文件以反映实际路径。例如，如果业务代码放在 `app/` 而非默认的 `src/`，将 `sourceRoots.src` 更新为 `["app"]`
+5. **写入实现清单**：在 `logos/resources/implementation/` 目录下创建实现清单文件（如 `implementation-manifest.md`），记录本次实现覆盖的场景、端点、用例 ID 等信息，标记 Phase 3-4 完成
 
 如果用户希望审查代码质量，引导使用 `code-reviewer` Skill。
 
 ## 输出规范
 
-- **业务代码**：输出到项目源码树（目录结构遵循架构设计中的约定）
-- **测试代码**：输出到项目测试目录
+- **业务代码**：输出到 `sourceRoots.src` 指定的目录（默认 `src/`，以 `logos.config.json` 配置为准）
+- **测试代码**：输出到 `sourceRoots.test` 指定的目录（默认 `test/`，以 `logos.config.json` 配置为准）
 - **Reporter**：嵌入测试代码中（非独立文件）
 - **JSONL 结果**：`logos/resources/verify/test-results.jsonl`
-- 本 Skill 不在 `logos/resources/` 下产出文件（代码进入项目源码树，JSONL 由测试运行时产出）
+- **实现清单**：`logos/resources/implementation/implementation-manifest.md`（所有批次完成后创建）
 
 ## 实践经验
 

package/spec/cli-json-output.md

@@ -0,0 +1,278 @@
+# CLI JSON 结构化输出规格
+
+> 版本: 1.0.0 | 创建日期: 2026-04-13
+
+## 1. 概述
+
+OpenLogos CLI 的 `status`、`verify`、`detect` 三个命令支持 `--format json` 参数，输出结构化 JSON 供外部工具（如 RunLogos）以编程方式消费。
+
+### 1.1 通用约定
+
+- **触发方式**：在命令后追加 `--format json`
+- **输出目标**：JSON 输出到 **stdout**；错误信息仍输出到 **stderr**
+- **JSON 格式**：紧凑单行输出（无缩进），方便管道处理
+- **退出码**：与人类可读模式保持一致
+- **编码**：UTF-8
+- **字段命名**：snake_case
+
+### 1.2 通用信封结构
+
+所有命令的 JSON 输出共享同一信封结构：
+
+```jsonc
+{
+  "command": "<command-name>",   // "status" | "verify" | "detect"
+  "version": "<cli-version>",   // CLI 版本号，如 "0.5.9"
+  "timestamp": "<ISO-8601>",    // 输出时间戳
+  "data": { ... }               // 命令特定的数据负载
+}
+```
+
+---
+
+## 2. `openlogos detect --format json`
+
+探测 CLI 版本和当前目录的项目信息。合并了 `--version` 的功能并扩展了项目探测能力。
+
+### 2.1 用法
+
+```bash
+openlogos detect                # 人类可读格式
+openlogos detect --format json  # JSON 格式
+```
+
+### 2.2 JSON Schema（data 部分）
+
+```jsonc
+{
+  "cli": {
+    "version": "0.5.9",           // CLI 版本号
+    "node_version": "v22.0.0"     // Node.js 运行时版本
+  },
+  "project": null | {             // null 表示当前目录不是 OpenLogos 项目
+    "name": "my-project",         // 项目名
+    "locale": "zh",               // 语言设置
+    "lifecycle": "active",        // "initial" | "active"
+    "description": "项目描述"      // 项目描述
+  }
+}
+```
+
+### 2.3 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `cli.version` | string | 是 | CLI 包版本号 |
+| `cli.node_version` | string | 是 | 当前 Node.js 版本（`process.version`）|
+| `project` | object \| null | 是 | 若当前目录含 `logos/logos.config.json` 则返回项目信息，否则 null |
+| `project.name` | string | 是 | 项目名（来自 config） |
+| `project.locale` | string | 是 | 项目语言设置 |
+| `project.lifecycle` | string | 是 | 项目生命周期阶段 |
+| `project.description` | string | 是 | 项目描述 |
+
+---
+
+## 3. `openlogos status --format json`
+
+### 3.1 用法
+
+```bash
+openlogos status                # 人类可读格式
+openlogos status --format json  # JSON 格式
+```
+
+### 3.2 JSON Schema（data 部分）
+
+```jsonc
+{
+  "phases": [
+    {
+      "key": "phase.1",
+      "label": "Phase 1 · 需求文档 (WHY)",
+      "done": true,
+      "files": ["01-requirements.md"]
+    },
+    {
+      "key": "phase.2",
+      "label": "Phase 2 · 产品设计 (WHAT)",
+      "done": false,
+      "files": []
+    }
+    // ... 所有 9 个 phase
+  ],
+  "active_proposals": [
+    {
+      "name": "add-feature",
+      "has_proposal": true,
+      "has_tasks": true,
+      "delta_count": 3
+    }
+  ],
+  "current_phase": "phase.2",      // 第一个未完成 phase 的 key，若全部完成则为 null
+  "suggestion": "对 AI 说：「基于需求文档做产品设计」",  // 建议的下一步操作
+  "all_done": false,               // 是否所有 phase 都已完成
+  "lifecycle": "active"            // 项目生命周期
+}
+```
+
+### 3.3 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `phases` | array | 是 | 所有阶段的状态列表（固定 9 个元素） |
+| `phases[].key` | string | 是 | 阶段标识符（如 `phase.1`, `phase.3-2-api`） |
+| `phases[].label` | string | 是 | 阶段的本地化标签 |
+| `phases[].done` | boolean | 是 | 该阶段是否已完成（有文件 = true） |
+| `phases[].files` | string[] | 是 | 该阶段目录下的文件列表 |
+| `active_proposals` | array | 是 | 活跃变更提案列表 |
+| `active_proposals[].name` | string | 是 | 提案目录名 |
+| `active_proposals[].has_proposal` | boolean | 是 | 是否存在 proposal.md |
+| `active_proposals[].has_tasks` | boolean | 是 | 是否存在 tasks.md |
+| `active_proposals[].delta_count` | number | 是 | deltas 目录下的文件数 |
+| `current_phase` | string \| null | 是 | 当前应推进的阶段 key；全部完成时为 null |
+| `suggestion` | string | 是 | 建议的下一步操作（本地化文本） |
+| `all_done` | boolean | 是 | 是否全部阶段已完成 |
+| `lifecycle` | string | 是 | 项目生命周期（`initial` 或 `active`） |
+
+---
+
+## 4. `openlogos verify --format json`
+
+### 4.1 用法
+
+```bash
+openlogos verify                # 人类可读格式
+openlogos verify --format json  # JSON 格式
+```
+
+### 4.2 JSON Schema（data 部分）
+
+```jsonc
+{
+  "summary": {
+    "defined_count": 10,          // 定义的测试用例总数
+    "ut_count": 6,                // 单元测试用例数
+    "st_count": 4,                // 场景测试用例数
+    "executed_count": 10,         // 已执行的测试用例数
+    "passed_count": 8,            // 通过数
+    "failed_count": 1,            // 失败数
+    "skipped_count": 1,           // 跳过数
+    "uncovered_count": 0,         // 未覆盖数
+    "coverage_pct": 100,          // 覆盖率百分比（整数）
+    "pass_rate_pct": 80           // 通过率百分比（整数）
+  },
+  "gate": {
+    "result": "FAIL",             // "PASS" | "FAIL"
+    "reason": "failed_cases"      // 失败原因分类，见下表
+  },
+  "failed_cases": [
+    {
+      "id": "UT-S01-03",
+      "error": "Expected 200, got 500"
+    }
+  ],
+  "uncovered_cases": ["ST-S02-01"],
+  "skipped_cases": ["UT-S01-05"],
+  "checklist": {
+    "total": 5,
+    "checked": 5,
+    "unchecked_items": []         // 未确认的覆盖度校验项
+  },
+  "ac_trace": {
+    "total": 4,
+    "passed": 3,
+    "failed_criteria": [
+      {
+        "ac_id": "S01-AC-02",
+        "description": "异常处理",
+        "linked_case_ids": ["ST-S01-02"],
+        "status": "FAIL"
+      }
+    ]
+  },
+  "report_path": "logos/resources/verify/acceptance-report.md"
+}
+```
+
+### 4.3 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `summary.defined_count` | number | 是 | 规格中定义的测试用例总数 |
+| `summary.ut_count` | number | 是 | 其中的 UT 数量 |
+| `summary.st_count` | number | 是 | 其中的 ST 数量 |
+| `summary.executed_count` | number | 是 | 实际执行的用例数 |
+| `summary.passed_count` | number | 是 | 通过的用例数 |
+| `summary.failed_count` | number | 是 | 失败的用例数 |
+| `summary.skipped_count` | number | 是 | 跳过的用例数 |
+| `summary.uncovered_count` | number | 是 | 未覆盖的用例数 |
+| `summary.coverage_pct` | number | 是 | 覆盖率（0-100 整数） |
+| `summary.pass_rate_pct` | number | 是 | 通过率（0-100 整数） |
+| `gate.result` | string | 是 | 门禁结果：`"PASS"` 或 `"FAIL"` |
+| `gate.reason` | string \| null | 是 | FAIL 时的原因分类，PASS 时为 null |
+| `failed_cases` | array | 是 | 失败的测试用例列表 |
+| `uncovered_cases` | string[] | 是 | 未覆盖的用例 ID 列表 |
+| `skipped_cases` | string[] | 是 | 跳过的用例 ID 列表 |
+| `checklist.total` | number | 是 | 覆盖度校验项总数 |
+| `checklist.checked` | number | 是 | 已确认的项数 |
+| `checklist.unchecked_items` | array | 是 | 未确认项列表（含 text 和 file） |
+| `ac_trace.total` | number | 是 | 验收条件总数 |
+| `ac_trace.passed` | number | 是 | 通过的验收条件数 |
+| `ac_trace.failed_criteria` | array | 是 | 未通过的验收条件列表 |
+| `report_path` | string | 是 | 生成的验收报告路径 |
+
+### 4.4 gate.reason 取值
+
+| 值 | 说明 |
+|----|------|
+| `null` | 门禁通过 |
+| `"failed_cases"` | 存在失败的测试用例 |
+| `"incomplete_coverage"` | 存在未覆盖的测试用例 |
+| `"checklist_incomplete"` | 设计时覆盖度校验未完全确认 |
+| `"ac_trace_incomplete"` | 验收条件追溯未完全通过 |
+
+---
+
+## 5. 错误处理
+
+当命令因错误退出时（如项目未初始化、找不到文件等），JSON 模式下输出错误 JSON 到 **stderr** 并以非零退出码退出：
+
+```jsonc
+{
+  "command": "<command-name>",
+  "version": "<cli-version>",
+  "timestamp": "<ISO-8601>",
+  "error": {
+    "code": "PROJECT_NOT_INITIALIZED",
+    "message": "logos/logos.config.json not found."
+  }
+}
+```
+
+### 5.1 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| `PROJECT_NOT_INITIALIZED` | 当前目录不是 OpenLogos 项目 |
+| `NO_TEST_RESULTS` | 找不到测试结果文件 |
+| `NO_TEST_CASES` | 找不到测试用例规格文件 |
+
+---
+
+## 6. 完整用法示例
+
+```bash
+# 获取项目状态（机器可读）
+openlogos status --format json | jq '.data.current_phase'
+
+# 获取 CLI 版本和项目探测信息
+openlogos detect --format json | jq '.data.cli.version'
+
+# 获取测试验收摘要
+openlogos verify --format json | jq '.data.gate.result'
+
+# 在脚本中检查门禁结果
+if openlogos verify --format json 2>/dev/null | jq -e '.data.gate.result == "PASS"' > /dev/null; then
+  echo "All tests passed!"
+fi
+```