@haiyangbg/buildbeat 0.0.0 → 1.21.0

package/src/constants.js

@@ -0,0 +1,199 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+export const CLI_VERSION = packageJson.version;
+export const SCAFFOLD_VERSION = `v${CLI_VERSION.split(".").slice(0, 2).join(".")}`;
+export const OUTPUT_SCHEMA_VERSION = 2;
+export const PRODUCT_NAME = "BuildBeat";
+export const LEGACY_PRODUCT_NAME = "Solobaton";
+export const MARKER_FILE = "BUILDBEAT.md";
+export const LEGACY_MARKER_FILE = "SOLOBATON.md";
+export const MANIFEST_PATH = ".buildbeat/manifest.json";
+export const LEGACY_MANIFEST_PATH = ".solobaton/manifest.json";
+export const MANIFEST_PATHS = [MANIFEST_PATH, LEGACY_MANIFEST_PATH];
+export const MANIFEST_SCHEMA_VERSION = 2;
+export const SUPPORTED_MANIFEST_SCHEMA_VERSIONS = [1, 2];
+
+export const GITIGNORE_BEGIN_MARKER = "# >>> buildbeat managed >>>";
+export const GITIGNORE_END_MARKER = "# <<< buildbeat managed <<<";
+export const LEGACY_GITIGNORE_BEGIN_MARKER = "# >>> solobaton managed >>>";
+export const LEGACY_GITIGNORE_END_MARKER = "# <<< solobaton managed <<<";
+export const GITIGNORE_MARKER_PAIRS = [
+  [GITIGNORE_BEGIN_MARKER, GITIGNORE_END_MARKER],
+  [LEGACY_GITIGNORE_BEGIN_MARKER, LEGACY_GITIGNORE_END_MARKER],
+];
+
+export const SCRIPT_NAMES = [
+  "bus-check.sh",
+  "design-preview.sh",
+  "drift-check.sh",
+  "pre-commit.sh",
+  "verify-status.sh",
+];
+
+export const COMMON_REQUIRED_FILES = [
+  ".claude/agents/reviewer.md",
+  "AGENTS.md",
+  "ARCHITECTURE.md",
+  "CLAUDE.md",
+  "contracts/PROTOCOL.md",
+  "pm/NOW.md",
+  "pm/changes/README.md",
+  "pm/decisions.md",
+  "pm/status/README.md",
+];
+
+// Optional, project-owned template libraries. They ship in the package so an
+// AI session can use them on demand, but they are never part of the default
+// init/adopt plan or the required scaffold surface.
+export const OPTIONAL_TEMPLATE_PREFIXES = ["standards/", "pm/adr/"];
+
+export const IGNORED_SCAN_DIRECTORIES = new Set([
+  ".claude",
+  ".codex",
+  ".git",
+  ".buildbeat",
+  ".solobaton",
+  ".next",
+  ".nuxt",
+  ".output",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "target",
+  "vendor",
+]);
+
+export const RENDER_REQUIRED_PLACEHOLDERS = {
+  ".claude/agents/reviewer.md": ["<项目名>"],
+  "AGENTS.md": [
+    "<项目名>",
+    "<N>",
+    "<代码仓1>",
+    "<代码仓2>",
+    "<被测仓>",
+    "<PreStop/drain 机制>",
+  ],
+  "ARCHITECTURE.md": [
+    "<项目名>",
+    "<项目是什么、给谁用、核心取舍>",
+    "<用户入口>",
+    "<前端/客户端>",
+    "<仓名>",
+    "<部署单元>",
+    "<网关/服务A>",
+    "<审计/可观测>",
+    "<服务B>",
+    "<服务C>",
+    "<项目根>",
+    "<代码仓1>",
+    "<代码仓2>",
+    "<说明>",
+    "<部署平台/区域>",
+    "<应用/服务清单:名称+ID+实例>",
+    "<入口/域名/LB>",
+    "<数据库/缓存>",
+    "<服务A 凭据>",
+    "<路径/获取命令>",
+    "<运行时 env 实查>",
+    "<平台 CLI 命令>",
+  ],
+  "BUILDBEAT.md": ["<X.Y>", "<yyyy-mm-dd>", "<默认|紧凑>"],
+  "contracts/PROTOCOL.md": [
+    "<项目名>",
+    "<vX.Y.Z>",
+    "<上线日期>",
+    "<代码子仓1>",
+    "<bus-baseline.json app 名或 n/a>",
+    "<边界A:服务X ↔ 服务Y>",
+    "<对齐点>",
+    "<怎么核的:实测命令/代码行/配置查询>",
+  ],
+  "gitignore.template": ["<代码仓1>", "<代码仓2>"],
+  "pm/NOW.md": ["<期名>", "<一句话状态>", "<快轨|标准轨|重轨>", "<期>", "<域>"],
+  "pm/decisions.md": [
+    "<yyyy-mm-dd>",
+    "<谁>",
+    "<包ID>",
+    "<默认 2–5 个真实取舍的收敛结论;单项决定直接写一句>",
+    "<文件/落点>",
+  ],
+  "pm/当期看板.md": [
+    "<期名>",
+    "<工作包名>",
+    "<这轮最终要交付什么结果,不用文件名代替>",
+    "<产品 / 全栈 / 测试;按需调用,各自仍只写自己的边界>",
+    "<为达成结果可自动继续的关联任务/AI视角/文件边界>",
+    "<带证据完成 / 必须由人处理的真实阻塞 / 用户明确的检查点>",
+    "<完成时填一条可核验的仓库相对路径 / candidate hash;未完成留空>",
+    "<N>",
+    "<Gate>",
+    "<需求1>",
+    "<跨边界接口/字段/机制 约定;契约口径落 `contracts/PROTOCOL.md`>",
+    "<对照需求清单 + 设计稿逐屏;上线前必过的清单>",
+  ],
+  "pm/adr/ADR-0000-template.md": [
+    "<标题>",
+    "<yyyy-mm-dd>",
+    "<为什么现在必须做这个长期技术决定>",
+    "<最终选择及其边界>",
+    "<正向、负向与回滚影响>",
+    "<方案 A / B / C 及未选原因>",
+    "<工作包 / 契约 / evidence 路径或 n/a>",
+  ],
+  "scripts/drift-check.sh": ["<应用1>", "<应用2>", "<代码子仓1>"],
+  "scripts/verify-status.sh": ["<套件1>", "<套件2>", "<代码子仓1>", "<代码子仓2>"],
+  "standards/STACK.md": [
+    "<项目名>",
+    "<运行时及版本约束>",
+    "<包管理器及 lockfile>",
+    "<主要语言与框架>",
+    "<数据库 / 缓存 / 消息设施>",
+    "<部署平台 / 容器基线>",
+    "<CI 与测试命令>",
+    "<许可证 / 供应链约束>",
+    "<.nvmrc / engines.node 的精确值；多值重复本行；无则 n/a>",
+    "<lockfile 文件名；多类重复本行；无则 n/a>",
+    "<Dockerfile FROM 镜像；多值重复本行；无则 n/a>",
+  ],
+  "standards/CODE.md": ["<项目名>", "<代码组织与命名约定>", "<项目特有禁止事项>"],
+  "standards/REVIEW.md": ["<项目名>", "<项目特有 Review 条件>"],
+  "standards/DESIGN.md": [
+    "<项目名>",
+    "<设计原则>",
+    "<排版 / 色彩 / 间距 token 来源>",
+    "<核心组件与复用边界>",
+    "<项目特有例外>",
+  ],
+  "指挥台.md": ["<被测仓>"],
+};
+
+export const FILE_POLICIES = {
+  REPLACE_IF_UNMODIFIED: "replace-if-unmodified",
+  // Schema 1 compatibility only. New plans and schema 2 manifests never emit
+  // this historical policy.
+  THREE_WAY_ONLY: "three-way-only",
+  PROJECT_OWNED: "project-owned",
+  MERGE_ONLY: "merge-only",
+};
+
+export function filePolicy(templatePath) {
+  if (templatePath === "gitignore.template") {
+    return FILE_POLICIES.MERGE_ONLY;
+  }
+  if (
+    templatePath === "CLAUDE.md" ||
+    templatePath === ".claude/agents/reviewer.md" ||
+    templatePath === "AGENTS.md" ||
+    templatePath === "BUILDBEAT.md" ||
+    templatePath === "指挥台.md" ||
+    (/^scripts\//.test(templatePath) && templatePath !== "scripts/verify-status.sh")
+  ) {
+    return FILE_POLICIES.REPLACE_IF_UNMODIFIED;
+  }
+  return FILE_POLICIES.PROJECT_OWNED;
+}

package/src/doctor.js

@@ -0,0 +1,267 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  CLI_VERSION,
+  COMMON_REQUIRED_FILES,
+  OUTPUT_SCHEMA_VERSION,
+  SCRIPT_NAMES,
+  SUPPORTED_MANIFEST_SCHEMA_VERSIONS,
+} from "./constants.js";
+import { inspectProject } from "./project.js";
+
+const LEVEL_ORDER = { error: 0, warning: 1, info: 2 };
+
+function add(findings, level, code, message, relativePath = null) {
+  findings.push({ level, code, message, path: relativePath });
+}
+
+function requiredFiles(installation) {
+  const scriptBase = installation.layout === "compact" ? "pm/scripts" : "scripts";
+  const operatorCard = installation.layout === "compact" ? "pm/指挥台.md" : "指挥台.md";
+  const localFiles = [installation.markerPath, operatorCard].filter(Boolean);
+  return [
+    ...COMMON_REQUIRED_FILES,
+    ...localFiles,
+    ...SCRIPT_NAMES.map((name) => `${scriptBase}/${name}`),
+  ];
+}
+
+function verifyStatusHasPlaceholders(target, layout) {
+  const relative = layout === "compact"
+    ? "pm/scripts/verify-status.sh"
+    : "scripts/verify-status.sh";
+  const filename = path.join(target, relative);
+  if (!existsSync(filename)) {
+    return { relative, unconfigured: false };
+  }
+  const text = readFileSync(filename, "utf8");
+  return { relative, unconfigured: text.includes("<套件1>") || text.includes("<代码子仓1>") };
+}
+
+export function runDoctor(targetInput) {
+  const inspection = inspectProject(targetInput);
+  const findings = [];
+  const { installation } = inspection;
+
+  if (!inspection.exists) {
+    add(findings, "error", "target.not_found", "Target directory does not exist.");
+  } else if (installation.state === "not-installed") {
+    add(findings, "error", "install.not_found", "No BuildBeat or legacy Solobaton installation was detected.");
+  } else if (installation.state === "mixed") {
+    add(
+      findings,
+      "error",
+      "install.mixed_layout",
+      "Multiple BuildBeat/legacy markers or default/compact layout signals coexist; ownership is ambiguous.",
+    );
+  } else if (installation.state === "partial") {
+    add(
+      findings,
+      "error",
+      "install.partial",
+      `A partial ${installation.layout} layout was detected without a version marker.`,
+    );
+  }
+
+  if (installation.state === "installed") {
+    if (!installation.version) {
+      add(findings, "error", "version.unreadable", `${installation.markerPath} has no readable installed version.`);
+    }
+    for (const relative of requiredFiles(installation)) {
+      if (!existsSync(path.join(inspection.target, relative))) {
+        add(findings, "error", "file.missing", "Required scaffold file is missing.", relative);
+      }
+    }
+    if (installation.namespace === "solobaton") {
+      add(
+        findings,
+        "info",
+        "install.legacy_namespace",
+        "A legacy Solobaton marker was detected; it remains readable, while new scaffolds use BuildBeat identifiers.",
+        installation.markerPath,
+      );
+    }
+    const verify = verifyStatusHasPlaceholders(inspection.target, installation.layout);
+    if (verify.unconfigured) {
+      add(
+        findings,
+        "warning",
+        "verification.unconfigured",
+        "verify-status still contains suite placeholders; L3 automation is not configured.",
+        verify.relative,
+      );
+    }
+  }
+
+  if (inspection.manifest.state === "missing" && installation.state === "installed") {
+    add(
+      findings,
+      "warning",
+      "manifest.missing",
+      "This is a legacy/unmanaged installation; safe automated upgrade and uninstall are unavailable.",
+      inspection.manifest.path,
+    );
+  } else if (inspection.manifest.state === "ambiguous") {
+    add(
+      findings,
+      "error",
+      "manifest.ambiguous",
+      "Both BuildBeat and legacy Solobaton lifecycle manifests exist; ownership is ambiguous.",
+      inspection.manifest.path,
+    );
+  } else if (inspection.manifest.state === "invalid") {
+    add(findings, "error", "manifest.invalid", "The lifecycle manifest is unreadable or invalid JSON.", inspection.manifest.path);
+  } else if (
+    inspection.manifest.state === "present" &&
+    inspection.manifest.schemaVersion !== null &&
+    !SUPPORTED_MANIFEST_SCHEMA_VERSIONS.includes(inspection.manifest.schemaVersion)
+  ) {
+    add(
+      findings,
+      "error",
+      "manifest.unsupported_schema",
+      `Manifest schema ${inspection.manifest.schemaVersion ?? "unknown"} is not supported.`,
+      inspection.manifest.path,
+    );
+  } else if (inspection.manifest.state === "present") {
+    for (const issue of inspection.manifest.validationIssues) {
+      add(findings, "error", issue.code, issue.message, inspection.manifest.path);
+    }
+    if (
+      installation.state === "installed" &&
+      ["default", "compact"].includes(inspection.manifest.layout) &&
+      inspection.manifest.layout !== installation.layout
+    ) {
+      add(
+        findings,
+        "error",
+        "manifest.layout_mismatch",
+        "Manifest layout does not match the detected installation layout.",
+        inspection.manifest.path,
+      );
+    }
+    if (
+      installation.state === "installed" &&
+      installation.version &&
+      /^v\d+\.\d+(?:\.\d+)?$/.test(inspection.manifest.scaffoldVersion || "") &&
+      inspection.manifest.scaffoldVersion !== installation.version
+    ) {
+      add(
+        findings,
+        "error",
+        "manifest.version_mismatch",
+        `Manifest scaffoldVersion does not match ${installation.markerPath}.`,
+        inspection.manifest.path,
+      );
+    }
+  }
+
+  for (const item of inspection.placeholders) {
+    add(
+      findings,
+      "warning",
+      "placeholder.remaining",
+      `Canonical placeholders remain: ${item.tokens.join(", ")}`,
+      item.path,
+    );
+  }
+
+  if (inspection.exists && !inspection.signals.hasGit) {
+    add(findings, "error", "git.not_initialized", "The target has no root .git entry.");
+  }
+  if (inspection.exists && inspection.hook.mode === "direct-non-executable") {
+    add(
+      findings,
+      "warning",
+      "hook.non_executable",
+      "The root pre-commit hook exists but is not executable.",
+      inspection.hook.path,
+    );
+  } else if (inspection.exists && !inspection.hook.configured) {
+    add(
+      findings,
+      "warning",
+      "hook.missing",
+      "No root pre-commit hook or core.hooksPath configuration was detected.",
+    );
+  }
+
+  for (const command of ["git", "bash"]) {
+    if (!inspection.dependencies[command].available) {
+      add(findings, "error", `dependency.${command}_missing`, `${command} is required but unavailable.`);
+    }
+  }
+  if (!inspection.dependencies.gitleaks.available) {
+    add(
+      findings,
+      "warning",
+      "dependency.gitleaks_missing",
+      "gitleaks is unavailable; the local Secret gate degrades to a warning.",
+    );
+  }
+  if (!inspection.dependencies.python3.available) {
+    add(findings, "info", "dependency.python_missing", "Python 3 is unavailable; design preview cannot run.");
+  }
+  if (!inspection.dependencies.jq.available) {
+    add(findings, "info", "dependency.jq_missing", "jq is unavailable; production drift checks cannot run.");
+  }
+  if (inspection.scan.truncated) {
+    add(
+      findings,
+      "warning",
+      "scan.truncated",
+      "Project scan hit the 5,000-entry safety limit; results are incomplete.",
+    );
+  }
+  for (const item of inspection.scan.warnings) {
+    add(findings, "warning", "scan.unreadable", `Path could not be inspected: ${item.reason}.`, item.path);
+  }
+
+  findings.sort((a, b) =>
+    LEVEL_ORDER[a.level] - LEVEL_ORDER[b.level] ||
+    a.code.localeCompare(b.code) ||
+    (a.path || "").localeCompare(b.path || ""),
+  );
+  const summary = {
+    errors: findings.filter((item) => item.level === "error").length,
+    warnings: findings.filter((item) => item.level === "warning").length,
+    info: findings.filter((item) => item.level === "info").length,
+  };
+
+  return {
+    schemaVersion: OUTPUT_SCHEMA_VERSION,
+    command: "doctor",
+    cliVersion: CLI_VERSION,
+    target: inspection.target,
+    installation: inspection.installation,
+    manifest: inspection.manifest,
+    capabilities: inspection.dependencies,
+    findings,
+    summary,
+    ok: summary.errors === 0,
+  };
+}
+
+export function formatDoctor(report) {
+  const lines = [
+    "BuildBeat doctor",
+    `Target: ${report.target}`,
+    `Installation: ${report.installation.state}${report.installation.layout ? ` (${report.installation.layout})` : ""}${report.installation.version ? ` ${report.installation.version}` : ""}`,
+    `Manifest: ${report.manifest.state}`,
+    "",
+  ];
+  if (report.findings.length === 0) {
+    lines.push("OK No findings.");
+  } else {
+    for (const finding of report.findings) {
+      const location = finding.path ? ` [${finding.path}]` : "";
+      lines.push(`${finding.level.toUpperCase()} ${finding.code}${location}: ${finding.message}`);
+    }
+  }
+  lines.push(
+    "",
+    `Result: ${report.summary.errors} error(s), ${report.summary.warnings} warning(s), ${report.summary.info} info item(s).`,
+  );
+  return lines.join("\n");
+}