@wandoupeas/coding-forge 0.1.0

package/dist/cli/commands/init.js

@@ -0,0 +1,303 @@
+/**
+ * init 命令 - 初始化项目
+ */
+import { Command } from 'commander';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import logger from '../utils/logger.js';
+import { createWorkspace } from '../../core/workspace.js';
+import { buildDoctorReport } from './doctor.js';
+import { buildOnboardingSummary } from './onboard.js';
+import { writeText } from '../../utils/file.js';
+export function createInitCommand() {
+    const command = new Command('init')
+        .description('初始化 WebForge 项目')
+        .argument('<project-name>', '项目名称')
+        .option('-t, --template <template>', '项目模板', 'default')
+        .action(async (projectName, options) => {
+        try {
+            await initProject(projectName, options);
+        }
+        catch (error) {
+            logger.error(`初始化失败: ${error}`);
+            process.exit(1);
+        }
+    });
+    return command;
+}
+export async function initProject(projectName, options, basePath = process.cwd()) {
+    logger.info(`初始化项目: ${projectName}\n`);
+    const projectRoot = join(basePath, projectName);
+    const state = await createWorkspace(projectRoot, {
+        projectName,
+        template: options.template
+    });
+    await scaffoldRepoContract(projectRoot, projectName);
+    const verification = await buildInitVerificationSummary(projectRoot);
+    if (!verification.ok) {
+        throw new Error(`初始化后自检失败: doctor.fail=${verification.doctorFailCount}, doctor.warn=${verification.doctorWarnCount}, onboard.canProceed=${verification.onboardCanProceed}, protocolDocExists=${verification.protocolDocExists}, shouldReadHasAgents=${verification.shouldReadHasAgents}`);
+    }
+    logger.h1('项目初始化完成!');
+    logger.h2('初始化后自检');
+    logger.info(`doctor: fail=${verification.doctorFailCount} | warn=${verification.doctorWarnCount}`);
+    logger.info(`onboard: canProceed=${verification.onboardCanProceed ? 'yes' : 'no'}`);
+    logger.info(`protocol doc: ${verification.protocolDocPath}`);
+    logger.info('验证入口: webforge verify init');
+    console.log();
+    logger.info('下一步:');
+    logger.list([
+        `cd ${projectName}`,
+        `workspace: ${state.paths.workspace}`,
+        `runtime: ${state.paths.runtime}`,
+        'webforge onboard --json',
+        '如需重跑初始化后自检，执行 webforge verify init',
+        '必要时再拆开执行 webforge doctor / webforge resume / webforge logs runtime',
+        '把需求文档放进 .webforge/knowledge/requirements/'
+    ]);
+    console.log();
+}
+async function scaffoldRepoContract(projectRoot, projectName) {
+    await writeIfMissing(join(projectRoot, 'AGENTS.md'), renderAgentsTemplate(projectName));
+    await writeIfMissing(join(projectRoot, 'docs', 'agent-guide.md'), renderAgentGuideTemplate(projectName));
+    await writeIfMissing(join(projectRoot, 'docs', 'methodology', 'superpowers-integration.md'), renderSuperpowersTemplate(projectName));
+    await writeIfMissing(join(projectRoot, 'docs', 'examples', 'agent-onboarding-protocol.md'), renderOnboardingProtocolTemplate(projectName));
+}
+async function writeIfMissing(path, content) {
+    if (existsSync(path)) {
+        return;
+    }
+    await writeText(path, content);
+}
+export async function buildInitVerificationSummary(projectRoot) {
+    const protocolDocPath = join(projectRoot, 'docs', 'examples', 'agent-onboarding-protocol.md');
+    const [doctor, onboarding] = await Promise.all([
+        buildDoctorReport(projectRoot),
+        buildOnboardingSummary(projectRoot)
+    ]);
+    const protocolDocExists = existsSync(protocolDocPath);
+    const shouldReadHasAgents = onboarding.shouldRead.includes('AGENTS.md');
+    const ok = protocolDocExists &&
+        doctor.summary.fail === 0 &&
+        doctor.summary.warn === 0 &&
+        onboarding.canProceed === true &&
+        shouldReadHasAgents;
+    return {
+        protocolDocPath,
+        protocolDocExists,
+        doctorFailCount: doctor.summary.fail,
+        doctorWarnCount: doctor.summary.warn,
+        onboardCanProceed: onboarding.canProceed,
+        shouldReadHasAgents,
+        ok
+    };
+}
+function renderAgentsTemplate(projectName) {
+    return `# ${projectName} WebForge 契约
+
+这个仓库使用 WebForge 作为 repo-side harness。
+你应直接以 Codex / Claude Code 身份在仓库里工作，并把 \`.webforge/\` 作为状态真相源。
+
+## 标准 Onboarding Protocol
+
+进入仓库后，默认先按这条协议工作：
+
+1. 运行 \`webforge onboard --json\`
+2. 读取返回的 \`shouldRead\`
+3. 检查 \`recommendedActions\`
+4. 如果 \`runtimeLogCommand\` 存在且出现 drift / blocked 信号，再运行对应的 \`webforge logs runtime <session>\`
+5. 如需示例，直接看 \`docs/examples/agent-onboarding-protocol.md\`
+
+如果你不走统一入口，至少也要按这个顺序拆开执行：
+
+1. \`webforge doctor --json\`
+2. \`webforge resume --json\`
+3. 必要时 \`webforge logs runtime --json\`
+
+## 进入仓库后的读取顺序
+
+1. 读取 \`.webforge/runtime.json\`
+2. 读取 \`.webforge/tasks.json\`
+3. 读取 \`.webforge/phases.json\`
+4. 读取 \`.webforge/sessions/index.json\`
+5. 读取 \`.webforge/knowledge/index.json\`
+6. 必要时再读取具体 knowledge、deliverable、mailbox 内容
+
+## 工作原则
+
+1. 不要发明第二套仓库外编排。
+2. 所有状态变化都回写到 \`.webforge/\`。
+3. CLI 是观察面和校验面，不是事实来源。
+4. 如需方法增强，可使用 \`superpowers\`，但它不是状态数据库。
+
+## 开始工作前
+
+1. 先读本文件和 \`.webforge/\`
+2. 优先运行 \`webforge onboard --json\`
+3. 如果出现 \`runtime-context-drift\` 或 \`contextDrift=drifted\`，先回看 runtime 日志
+4. 再决定下一步工作
+`;
+}
+function renderAgentGuideTemplate(projectName) {
+    return `# ${projectName} Agent Guide
+
+## 目标
+
+本仓库通过 WebForge 约束 Codex / Claude Code 的工作方式，而不是再包一层外部 orchestrator。
+
+## 建议工作顺序
+
+1. 读取 \`AGENTS.md\`
+2. 运行 \`webforge onboard --json\`
+3. 按 \`shouldRead\` 读取 \`.webforge/runtime.json\`、\`tasks.json\`、\`sessions/index.json\` 等文件
+4. 如果 \`recommendedActions\` 提示 drift，先运行 \`webforge logs runtime <session>\`
+5. 如需照着执行的示例，先看 \`docs/examples/agent-onboarding-protocol.md\`
+6. 需要设计时使用 \`brainstorming\`
+7. 需要计划时使用 \`writing-plans\`
+8. 完成工作后把结果回写到 \`.webforge/\`
+
+## 恢复协议
+
+\`onboard --json\` 是统一入口，会合并：
+
+- \`doctor --json\`
+- \`resume --json\`
+- 最近一次 runtime 日志跳转
+- 当前 \`workflow context / thread linkage\` 的恢复健康度
+
+如果你需要拆开排查，按这个顺序：
+
+1. \`webforge doctor --json\`
+2. \`webforge resume --json\`
+3. \`webforge logs runtime --json\`
+
+当 \`doctor\` 出现 \`runtime-context-drift\`，或 \`resume.runtimeLog.contextDrift=drifted\` 时，不要直接沿当前上下文继续，先核对最近 runtime 与当前 workspace 的差异。
+
+## 最低回写要求
+
+- 任务推进: 更新 \`.webforge/tasks.json\`
+- 执行状态: 更新 \`.webforge/runtime.json\`
+- 新知识: 更新 \`.webforge/knowledge/\`
+- 新交付物: 更新 \`.webforge/deliverables/\`
+`;
+}
+function renderSuperpowersTemplate(projectName) {
+    return `# ${projectName} Superpowers Integration
+
+## 边界
+
+- WebForge 负责仓库状态、恢复入口和执行协议
+- superpowers 负责设计、计划、评审、compact、线程化恢复等方法增强
+
+## 推荐映射
+
+- 设计收敛: \`brainstorming\`
+- 计划拆解: \`writing-plans\`
+- 实施执行: \`subagent-driven-development\`
+- 会话压缩: \`strategic-compact\`
+- 长程偏好学习: \`continuous-learning-v2\`
+
+## 与恢复协议的连接点
+
+- superpowers 产物必须回写到 \`.webforge/superpowers-runs.json\`
+- thread / compact / worktree 线索必须能被 \`doctor / onboard / resume / logs\` 读到
+- 如果最新 workflow 结果和当前 workspace 已经漂移，优先让 agent 回看 runtime 日志，而不是盲目继续
+
+## 禁止事项
+
+1. 不要把 superpowers 当作 \`.webforge/\` 的替代品
+2. 不要把 superpowers 当作唯一记忆源
+3. 不要让方法层覆盖仓库内状态契约
+`;
+}
+function renderOnboardingProtocolTemplate(projectName) {
+    return `# ${projectName} Agent Onboarding Protocol
+
+这份文档给进入本仓库工作的 Codex / Claude Code 使用。
+
+目标只有一个：先恢复正确上下文，再决定要不要继续实现。
+
+## 标准入口
+
+优先使用统一入口：
+
+\`\`\`bash
+webforge onboard --json
+\`\`\`
+
+你需要从输出里依次处理：
+
+1. \`doctor.summary\`
+   如果 \`fail > 0\`，先修仓库契约，不要直接开发。
+2. \`resume.shouldRead\`
+   只读取这些必要文件，不要一上来扫描整个仓库。
+3. \`resume.nextAction\`
+   这是当前最推荐的下一步。
+4. \`recommendedActions\`
+   如果这里提示 drift / blocked / pending_review，先处理这些信号。
+
+## 拆开排查时的顺序
+
+如果你不想走统一入口，按这个顺序：
+
+\`\`\`bash
+webforge doctor --json
+webforge resume --json
+webforge logs runtime --json
+\`\`\`
+
+含义分别是：
+
+- \`doctor --json\`
+  看仓库契约是否完整，以及最近 runtime 上下文有没有和当前 workspace 脱节
+- \`resume --json\`
+  看下一步该做什么，以及应该读哪些文件
+- \`logs runtime --json\`
+  看最近 runtime 事件流、日志恢复快照、当前工作区恢复快照
+
+## 遇到 drift 时怎么做
+
+如果出现下面任一信号：
+
+- \`doctor.checks.runtime-context-drift.status = warn\`
+- \`resume.runtimeLog.contextDrift.status = drifted\`
+- \`recommendedActions\` 明确要求先回看 runtime
+
+那么先执行：
+
+\`\`\`bash
+webforge logs runtime
+\`\`\`
+
+先确认：
+
+1. 最近 runtime 对应的 \`workflowContext / threadLinkage\`
+2. 当前工作区最新的 \`workflowContext / threadLinkage\`
+3. 两者为什么不同
+
+没有核对 drift 之前，不要默认沿当前上下文直接继续。
+
+## 开始实现前至少要读
+
+- \`AGENTS.md\`
+- \`.webforge/runtime.json\`
+- \`.webforge/tasks.json\`
+- \`.webforge/sessions/index.json\`
+- \`.webforge/knowledge/index.json\`
+
+如果 \`shouldRead\` 还带了其他文件，以 \`shouldRead\` 为准。
+
+## 完成后必须回写
+
+- 任务变化回写到 \`.webforge/tasks.json\`
+- 执行状态回写到 \`.webforge/runtime.json\`
+- 新知识回写到 \`.webforge/knowledge/\`
+- 新交付物回写到 \`.webforge/deliverables/\`
+
+一句话：
+
+\`\`\`text
+onboard --json -> read shouldRead -> inspect drift if needed -> execute -> write back to .webforge/
+\`\`\`
+`;
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/knowledge.d.ts

@@ -0,0 +1,6 @@
+/**
+ * knowledge 命令 - 知识摄入
+ */
+import { Command } from 'commander';
+export declare function createKnowledgeCommand(): Command;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/cli/commands/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/knowledge.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,wBAAgB,sBAAsB,IAAI,OAAO,CAQhD"}