soloforge 1.3.1 → 1.3.3

package/dist/bin/soloforge.js

@@ -81,6 +81,9 @@ async function main() {
         case "validate-release":
             await cmdValidateReleaseGate();
             break;
+        case "audit-template-visibility":
+            await cmdAuditTemplateVisibility();
+            break;
         case "sync-templates":
             await cmdSyncTemplates();
             break;
@@ -132,6 +135,12 @@ async function main() {
         case "status":
             await cmdStatus();
             break;
+        case "next":
+            await cmdNext();
+            break;
+        case "stage":
+            await cmdStage();
+            break;
         case "cleanup":
             await cmdCleanup();
             break;
@@ -170,6 +179,11 @@ async function main() {
   config confirm <field> <value>  确认配置字段（写入 config + evidence）
   config unset <field>  移除确认配置
   status                显示当前项目的 SoloForge 状态
+  next                  查询下一步操作和可执行工作包（默认只读）
+  next --json           纯 JSON 输出（无日志污染）
+  next --write-snapshot 将导航快照写入 .soloforge/navigation-snapshot.json
+  stage                 显示当前项目阶段和任务阶段
+  stage --explain       详细解释当前阶段（判断依据、必要条件、下一阶段）
   cleanup               清理过期任务和 evidence（默认 dry-run，--apply 执行实际清理）
 `);
     }
@@ -460,56 +474,32 @@ async function cmdInit() {
                 "请打开 Claude Code 开始使用。"}`);
 }
 async function copyGlobalPatterns(projectPath) {
+    const { copyPatternsToGlobal } = await import("../engine/template_init_sync.js");
     const globalDir = getGlobalPatternsDir();
-    fss.mkdirSync(globalDir, { recursive: true });
-    const templatesDir = path.resolve(import.meta.dirname, "..", "..", "templates", "patterns");
-    if (fss.existsSync(templatesDir)) {
-        const files = fss.readdirSync(templatesDir).filter((f) => f.endsWith(".md"));
-        let copiedCount = 0;
-        let skippedCount = 0;
-        for (const f of files) {
-            const src = path.join(templatesDir, f);
-            const dest = path.join(globalDir, f);
-            if (!fss.existsSync(dest)) {
-                fss.copyFileSync(src, dest);
-                copiedCount++;
-            }
-            else {
-                skippedCount++;
-            }
-        }
-        const parts = [];
-        if (copiedCount > 0)
-            parts.push(`新增 ${copiedCount} 个`);
-        if (skippedCount > 0)
-            parts.push(`跳过 ${skippedCount} 个（已存在）`);
-        userInfo(`✅ 全局模板 ~/.soloforge/patterns/: ${parts.length > 0 ? parts.join("，") : `${files.length} 个（已全部存在）`}`);
+    const templatesRoot = path.resolve(import.meta.dirname, "..", "..");
+    const result = await copyPatternsToGlobal(templatesRoot, globalDir);
+    const parts = [];
+    if (result.copied > 0)
+        parts.push(`新增 ${result.copied} 个`);
+    if (result.skipped > 0)
+        parts.push(`跳过 ${result.skipped} 个（已存在）`);
+    if (parts.length > 0) {
+        userInfo(`✅ 全局模板 ~/.soloforge/patterns/: ${parts.join("，")}`);
     }
 }
 async function copyKnowledgeTemplates(projectPath) {
-    const knowledgeTemplatesDir = path.resolve(import.meta.dirname, "..", "..", "templates", "knowledge");
-    if (fss.existsSync(knowledgeTemplatesDir)) {
-        const subDirs = ["procedures", "domain", "product_profiles", "acceptance_templates", "review_rules", "patterns/core", "checklists", "templates"];
-        let copiedCount = 0;
-        for (const subDir of subDirs) {
-            const srcDir = path.join(knowledgeTemplatesDir, subDir);
-            if (!fss.existsSync(srcDir))
-                continue;
-            const destDir = path.join(projectPath, ".soloforge", "knowledge", subDir);
-            fss.mkdirSync(destDir, { recursive: true });
-            const files = fss.readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".yaml") || f.endsWith(".yml"));
-            for (const f of files) {
-                const src = path.join(srcDir, f);
-                const dest = path.join(destDir, f);
-                if (!fss.existsSync(dest)) {
-                    fss.copyFileSync(src, dest);
-                    copiedCount++;
-                }
-            }
-        }
-        if (copiedCount > 0) {
-            userInfo(`✅ ${copiedCount} 个知识模板已复制到 .soloforge/knowledge/`);
-        }
+    const { copyKnowledgeToProject } = await import("../engine/template_init_sync.js");
+    const templatesRoot = path.resolve(import.meta.dirname, "..", "..");
+    const result = await copyKnowledgeToProject(templatesRoot, projectPath);
+    const parts = [];
+    if (result.copied > 0)
+        parts.push(`${result.copied} 个已复制`);
+    if (result.skipped_internal > 0)
+        parts.push(`${result.skipped_internal} 个内部资产已跳过`);
+    if (result.skipped_no_contract > 0)
+        parts.push(`${result.skipped_no_contract} 个无合同已跳过`);
+    if (parts.length > 0) {
+        userInfo(`✅ 知识模板: ${parts.join("，")}`);
     }
 }
 async function generateAdapterConfigs(projectPath, adapter) {
@@ -870,8 +860,7 @@ async function cmdValidate() {
     try {
         const { config, source } = await resolveProjectConfig(projectPath);
         if (source === "inferred") {
-            userInfo("ℹ️  未找到 .soloforge/config.yaml — 使用自动推断的配置。");
-            userInfo("   运行 'soloforge init --auto' 可持久化。");
+            userInfo("ℹ️  配置来源: 自动推断");
         }
         else {
             userInfo("✅ config.yaml 有效");
@@ -1068,6 +1057,18 @@ async function cmdValidate() {
                 hasHardFail = true;
             }
         } // 双层机制检查结束
+        try {
+            const { planNextAction } = await import("../engine/next_action_planner.js");
+            const navigation = await planNextAction(projectPath);
+            userInfo(`  阶段: ${navigation.project_stage}${navigation.task_stage ? ` / ${navigation.task_stage}` : ""}`);
+            if (navigation.blocking_reasons.length > 0) {
+                userInfo(`  导航阻断: ${navigation.blocking_reasons.join("; ")}`);
+            }
+            userInfo(`  下一步: ${navigation.work_package?.goal_zh ?? navigation.recommended_prompt_zh}`);
+        }
+        catch (e) {
+            userInfo(`  ⚠ 导航摘要异常: ${e instanceof Error ? e.message : String(e)}`);
+        }
         if (hasHardFail) {
             userError("❌ validate 失败: 配置优先级存在 hard_fail");
             process.exit(1);
@@ -1590,14 +1591,14 @@ async function cmdSyncTemplates() {
     else {
         userInfo(apply ? "模板同步: apply 模式" : "模板同步: dry-run 模式（不写入文件）");
         userInfo(`  资产总数: ${assets.length}`);
-        userInfo(`  安全检查: ${safeCheck.safe ? "✓" : "✗"}`);
+        userInfo(`  应用安全: ${safeCheck.safe ? "安全" : "需确认"}`);
         userInfo(`  结果: ${syncResult.success ? "成功" : "失败"}`);
         userInfo(`  新增: ${syncResult.report.added.length}`);
         userInfo(`  更新: ${syncResult.report.updated.length}`);
         userInfo(`  跳过(用户修改): ${syncResult.report.skipped_user_modified.length}`);
         userInfo(`  废弃: ${syncResult.report.deprecated.length}`);
         if (!apply)
-            userInfo("  使用 --apply --confirm 应用同步");
+            userInfo("  使用 --apply --confirm 应用同步；需确认表示 dry-run 发现现有用户资产，不会自动覆盖");
     }
     if (!syncResult.success)
         process.exit(1);
@@ -1973,8 +1974,8 @@ async function cmdValidateNewIssue() {
         userInfo(JSON.stringify(output, null, 2));
     }
     else {
-        userInfo(`问题演进门控: ${output.gate_status}`);
-        userInfo(`  已检查 ${allProblems.length} 个既有问题`);
+        userInfo(`需求演进检查: ${output.gate_status}`);
+        userInfo(`  已检查 ${allProblems.length} 个已有功能记录`);
         if (output.duplicate_detected) {
             userInfo(`  ⚠ 重复检测: 发现 ${output.duplicates.join(", ")}`);
             for (const d of matchedDetails) {
@@ -1987,7 +1988,7 @@ async function cmdValidateNewIssue() {
                 userInfo(`    - ${r}`);
         }
         if (output.can_proceed) {
-            userInfo(`  ✓ 可继续: 问题新增已通过演进门控 (候选ID: ${candidateId})`);
+            userInfo(`  ✓ 可继续: 需求新增已通过演进检查 (ID: ${candidateId})`);
         }
     }
     if (!output.can_proceed) {
@@ -1997,8 +1998,8 @@ async function cmdValidateNewIssue() {
 async function cmdStatus() {
     debug("CLI", "执行 cmdStatus");
     const projectPath = resolveProjectPath();
-    userInfo(`SoloForge 状态: ${projectPath}`);
     const { config, source } = await resolveProjectConfig(projectPath);
+    userInfo(`SoloForge 状态: ${projectPath}`);
     userInfo(`  配置来源: ${source === "config_file" ? "config.yaml" : "自动推断"}`);
     userInfo(`  产品: ${config.product_profile}`);
     userInfo(`  后端: ${config.tech_stack.backend.framework || "未配置"}`);
@@ -2051,6 +2052,19 @@ async function cmdStatus() {
     else {
         userInfo("  知识: 未初始化");
     }
+    // 导航摘要（消费同一规划模块，包含阻断项和下一步）
+    try {
+        const { planNextAction } = await import("../engine/next_action_planner.js");
+        const navigation = await planNextAction(projectPath);
+        userInfo(`  阶段: ${navigation.project_stage}${navigation.task_stage ? ` / ${navigation.task_stage}` : ""}`);
+        if (navigation.blocking_reasons.length > 0) {
+            userInfo(`  导航阻断: ${navigation.blocking_reasons.join("; ")}`);
+        }
+        userInfo(`  下一步: ${navigation.work_package?.goal_zh ?? navigation.recommended_prompt_zh}`);
+    }
+    catch (e) {
+        userInfo(`  ⚠ 导航摘要异常: ${e instanceof Error ? e.message : String(e)}`);
+    }
 }
 async function interactiveConfig(projectPath) {
     debug("CLI", "执行 interactiveConfig");
@@ -2113,6 +2127,200 @@ function cmdVersion() {
         userInfo("SoloForge v" + pkg.version);
     }
 }
+async function cmdNext() {
+    debug("CLI", "执行 cmdNext");
+    const projectPath = resolveProjectPath();
+    const isJson = args.includes("--json");
+    const writeSnapshot = args.includes("--write-snapshot");
+    const { planNextAction } = await import("../engine/next_action_planner.js");
+    const plan = await planNextAction(projectPath);
+    if (isJson) {
+        // JSON 模式: 纯 JSON 到 stdout，无日志污染
+        const wp = plan.work_package;
+        const output = {
+            project_stage: plan.project_stage,
+            task_stage: plan.task_stage,
+            confidence: plan.confidence,
+            stage_evidence: plan.stage_evidence,
+            blocking_reasons: plan.blocking_reasons,
+            recommended_commands: plan.recommended_commands,
+            recommended_prompt: plan.recommended_prompt_zh,
+            disallowed_next_actions: plan.disallowed_actions.map((da) => ({
+                rule_id: da.rule_id,
+                blocked_actions: da.blocked_actions,
+                reason_zh: da.reason_zh,
+            })),
+            work_package: wp ? {
+                id: wp.id,
+                goal: wp.goal_zh,
+                input_files: wp.input_files,
+                must_read: wp.must_read,
+                forbidden_changes: wp.forbidden_changes,
+                expected_outputs: wp.expected_outputs,
+                acceptance_commands: wp.acceptance_commands,
+                user_confirmation_points: wp.user_confirmation_points,
+                rollback_or_fallback: wp.rollback_or_fallback,
+            } : null,
+        };
+        process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+    }
+    else {
+        // 人类可读输出
+        userInfo(`\n项目阶段: ${plan.project_stage}`);
+        if (plan.task_stage) {
+            userInfo(`任务阶段: ${plan.task_stage}`);
+        }
+        else {
+            userInfo("任务阶段: 无活跃任务");
+        }
+        userInfo(`置信度: ${plan.confidence}`);
+        if (plan.stage_evidence.length > 0) {
+            userInfo(`\n判断依据:`);
+            for (const ev of plan.stage_evidence) {
+                userInfo(`  - ${ev}`);
+            }
+        }
+        // 陈旧任务
+        if (plan.stale_task?.is_stale) {
+            userInfo(`\n⚠️  检测到陈旧任务: ${plan.stale_task.reason_zh}`);
+            userInfo(`  任务 ID: ${plan.stale_task.task_id}`);
+            userInfo(`  建议操作: ${plan.stale_task.suggested_resolutions.join(" / ")}`);
+            userInfo(`  ⚠️  不要绕过 SoloForge 状态直接操作`);
+        }
+        // 阻断项
+        if (plan.blocking_reasons.length > 0) {
+            userInfo(`\n阻断项:`);
+            for (const r of plan.blocking_reasons) {
+                userInfo(`  - ${r}`);
+            }
+        }
+        // 工作包
+        if (plan.work_package) {
+            const wp = plan.work_package;
+            userInfo(`\n下一步: ${wp.goal_zh}`);
+            userInfo(`  描述: ${wp.description_zh}`);
+            if (wp.tool_name) {
+                userInfo(`  工具: ${wp.tool_name}`);
+            }
+            if (wp.must_read.length > 0) {
+                userInfo(`  必读文件:`);
+                for (const f of wp.must_read)
+                    userInfo(`    - ${f}`);
+            }
+            if (wp.forbidden_changes.length > 0) {
+                userInfo(`  禁止操作:`);
+                for (const f of wp.forbidden_changes)
+                    userInfo(`    - ${f}`);
+            }
+            if (wp.expected_outputs.length > 0) {
+                userInfo(`  预期产出:`);
+                for (const e of wp.expected_outputs)
+                    userInfo(`    - ${e}`);
+            }
+            if (wp.acceptance_commands.length > 0) {
+                userInfo(`  验收命令:`);
+                for (const c of wp.acceptance_commands)
+                    userInfo(`    - ${c}`);
+            }
+            if (wp.user_confirmation_points.length > 0) {
+                userInfo(`  需用户确认:`);
+                for (const u of wp.user_confirmation_points)
+                    userInfo(`    - ${u}`);
+            }
+            if (wp.rollback_or_fallback.length > 0) {
+                userInfo(`  失败回退:`);
+                for (const r of wp.rollback_or_fallback)
+                    userInfo(`    - ${r}`);
+            }
+        }
+        // 推荐命令
+        if (plan.recommended_commands.length > 0) {
+            userInfo(`\n推荐命令:`);
+            for (const c of plan.recommended_commands) {
+                userInfo(`  ${c}`);
+            }
+        }
+        // 禁止动作
+        if (plan.disallowed_actions.length > 0) {
+            userInfo(`\n禁止动作:`);
+            for (const da of plan.disallowed_actions) {
+                userInfo(`  [${da.rule_id}] ${da.blocked_actions.join(", ")}: ${da.reason_zh}`);
+            }
+        }
+        // 推荐给 AI 的指令
+        userInfo(`\n推荐指令: ${plan.recommended_prompt_zh}`);
+    }
+    // 写入快照（只在显式 --write-snapshot 时）
+    if (writeSnapshot) {
+        const snapshotPath = path.join(projectPath, ".soloforge", "navigation-snapshot.json");
+        const snapshot = {
+            plan_id: plan.plan_id,
+            generated_at: plan.generated_at,
+            project_stage: plan.project_stage,
+            task_stage: plan.task_stage,
+            current_task_id: plan.current_task_id,
+            work_package: plan.work_package,
+        };
+        fss.mkdirSync(path.join(projectPath, ".soloforge"), { recursive: true });
+        fss.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
+        if (!isJson) {
+            userInfo(`\n导航快照已写入: ${snapshotPath}`);
+        }
+    }
+}
+async function cmdStage() {
+    debug("CLI", "执行 cmdStage");
+    const projectPath = resolveProjectPath();
+    const explain = args.includes("--explain");
+    const isJson = args.includes("--json");
+    const { detectProjectStage, explainProjectStage } = await import("../engine/project_stage_detector.js");
+    const { detectTaskStage, explainTaskStage } = await import("../engine/task_stage_detector.js");
+    const projectStage = await detectProjectStage(projectPath);
+    // 加载当前任务
+    let taskStage = null;
+    let taskId = null;
+    try {
+        const { TaskContextManager } = await import("../engine/task_context.js");
+        const stateDir = path.join(projectPath, ".soloforge", "state");
+        if (fss.existsSync(stateDir)) {
+            const manager = new TaskContextManager(stateDir);
+            const ctx = await manager.getCurrentTask();
+            if (ctx) {
+                taskStage = detectTaskStage(ctx);
+                taskId = ctx.task_id;
+            }
+        }
+    }
+    catch { }
+    if (isJson) {
+        const projExplanation = explainProjectStage(projectStage);
+        process.stdout.write(JSON.stringify({
+            project: projExplanation,
+            task: taskStage ? explainTaskStage(taskStage) : null,
+            task_id: taskId,
+        }, null, 2) + "\n");
+        return;
+    }
+    userInfo(`\n项目阶段: ${projectStage}`);
+    if (explain) {
+        const projExplanation = explainProjectStage(projectStage);
+        userInfo(`  ${projExplanation.description_zh}`);
+        userInfo(`  必要条件: ${projExplanation.required_evidence.join(", ") || "无"}`);
+        userInfo(`  下一步可能: ${projExplanation.next_possible_stages.join(", ")}`);
+    }
+    if (taskStage) {
+        userInfo(`\n任务阶段: ${taskStage} (${taskId ?? "unknown"})`);
+        if (explain) {
+            const taskExplanation = explainTaskStage(taskStage);
+            userInfo(`  ${taskExplanation.description_zh}`);
+            userInfo(`  必要条件: ${taskExplanation.required_evidence.join(", ")}`);
+            userInfo(`  下一步可能: ${taskExplanation.next_possible_stages.join(", ")}`);
+        }
+    }
+    else {
+        userInfo("\n当前无活跃任务");
+    }
+}
 async function cmdCleanup() {
     debug("CLI", "执行 cmdCleanup");
     const dryRun = !args.includes("--apply");
@@ -2266,4 +2474,58 @@ function getArgValue(flag) {
         return undefined;
     return result;
 }
+async function cmdAuditTemplateVisibility() {
+    const projectPath = process.env.SOLOFORGE_PROJECT ?? process.cwd();
+    const { auditStandardAssetCoverage } = await import("../engine/standard_asset_coverage.js");
+    const { listBuiltinConsumableAssets } = await import("../engine/consumable_asset_registry.js");
+    const { listTemplateAssetContracts, auditContractCoverage } = await import("../engine/template_asset_contract_registry.js");
+    const { userInfo, userJson } = await import("../engine/logger.js");
+    // 使用权威合同注册表作为单一数据源
+    const contracts = listTemplateAssetContracts();
+    const registeredAssets = listBuiltinConsumableAssets();
+    const consumablePaths = new Set(registeredAssets.map((a) => a.path));
+    const ownerMap = new Map(contracts.map((c) => [c.path, c.owner_mechanism_id]));
+    const consumerMap = new Map(contracts.map((c) => [c.path, [c.mainline_consumer, c.validation_entrypoint].filter(Boolean)]));
+    const visibilityMap = new Map(contracts.map((c) => [c.path, c.asset_visibility]));
+    // 运行覆盖审计（使用真实合同数据）
+    const report = auditStandardAssetCoverage(projectPath, consumablePaths, ownerMap, consumerMap, visibilityMap);
+    // 合同覆盖统计
+    const coverageReport = auditContractCoverage(projectPath);
+    // 可见性统计（从权威合同直接计算）
+    const internalCount = contracts.filter((c) => c.asset_visibility === "soloforge_internal" || c.asset_visibility === "scaffold_only").length;
+    const userVisibleCount = contracts.filter((c) => c.user_visible).length;
+    // 输出报告
+    const isJson = args.includes("--json");
+    const result = {
+        total_assets: report.total_assets,
+        contract_covered: coverageReport.contract_covered,
+        uncovered_assets: coverageReport.uncovered,
+        user_visible_count: userVisibleCount,
+        internal_count: internalCount,
+        unknown_visibility: coverageReport.visibility_unknown,
+        conflict_count: 0,
+        missing_bearer: report.missing_standard_bearer,
+        missing_revalidation: report.missing_revalidation,
+        missing_consumer: report.missing_consumer,
+        missing_owner: report.missing_owner,
+        unregistered: report.unregistered_assets,
+    };
+    if (isJson) {
+        userJson(JSON.stringify(result, null, 2));
+    }
+    else {
+        userInfo("═══ 模板资产可见性审计报告 ═══");
+        userInfo(`总资产数:       ${report.total_assets}`);
+        userInfo(`合同覆盖:       ${coverageReport.contract_covered}`);
+        userInfo(`未覆盖:         ${coverageReport.uncovered}`);
+        userInfo(`用户可见:       ${userVisibleCount}`);
+        userInfo(`内部资产:       ${internalCount}`);
+        userInfo(`未知可见性:     ${coverageReport.visibility_unknown}`);
+        userInfo(`缺标准承载:     ${report.missing_standard_bearer}`);
+        userInfo(`缺复验入口:     ${report.missing_revalidation}`);
+        userInfo(`缺消费者:       ${report.missing_consumer}`);
+        userInfo(`缺 owner:       ${report.missing_owner}`);
+        userInfo(`未注册:         ${report.unregistered_assets}`);
+    }
+}
 //# sourceMappingURL=soloforge.js.map