@dommaker/harness 1.6.0 → 1.8.0

package/dist/cli/commands/scaffold-templates.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * 脚手架模板数据（harness#132）
+ *
+ * 受管文件的正文正本，纯数据 + 纯渲染，零 IO、零上色——落盘语义与文案在
+ * `scaffold.ts` 的 plan 里，本模块只回答「这个文件的内容是什么」。
+ *
+ * 刻意留在代码内而不落 `templates/` 目录：`templates/` 无运行时消费者
+ * （harness 自身不读它），发布完整性清单（`release/integrity.ts`）也不覆盖它。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CHECKPOINT_FILE = exports.DEFAULT_CHECKPOINTS = exports.CUSTOM_CONSTRAINTS_TEMPLATE = exports.GITHUB_ACTIONS_SNIPPET = exports.HARNESS_CHECK_WORKFLOW = exports.GITLAB_CI_SNIPPET = exports.PRE_PUSH_SNIPPET = exports.PRE_COMMIT_SNIPPET = void 0;
+exports.renderPreCommitHook = renderPreCommitHook;
+exports.renderPrePushHook = renderPrePushHook;
+exports.renderGitLabCiJobs = renderGitLabCiJobs;
+exports.renderGitLabCiFile = renderGitLabCiFile;
+exports.renderGovernanceWorkflow = renderGovernanceWorkflow;
+exports.renderChangelog = renderChangelog;
+exports.renderContextDoc = renderContextDoc;
+exports.renderCheckpoints = renderCheckpoints;
+exports.renderResolutions = renderResolutions;
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+/** Git pre-commit 片段（#103：打印片段与落盘 hook 的唯一正本） */
+exports.PRE_COMMIT_SNIPPET = `
+echo "🔍 Running harness checks..."
+
+STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+
+# Harness 约束检查
+npx @dommaker/harness check --staged
+if [ $? -ne 0 ]; then
+  echo "❌ Iron law check failed"
+  exit 1
+fi
+
+# Plan coverage check (via PostEval)
+if command -v npx > /dev/null 2>&1; then
+  PLAN_FILES=$(echo "$STAGED" | grep -E 'plans/.*\\.md$|\\.plan\\.md$' || true)
+  if [ -n "$PLAN_FILES" ]; then
+    echo "📋 Checking plan coverage..."
+    for plan in $PLAN_FILES; do
+      npx @dommaker/harness posteval-plan "$plan" || {
+        echo "🛑 Plan coverage incomplete. See above for missed items."
+        exit 1
+      }
+    done
+  fi
+fi
+
+echo "✅ All checks passed"
+`;
+/** 落盘的 pre-commit hook = shebang + 说明行 + 共享片段 */
+function renderPreCommitHook() {
+    return `#!/bin/sh
+# Harness pre-commit hook
+${exports.PRE_COMMIT_SNIPPET}`;
+}
+/**
+ * Git pre-push 片段（harness#144；#103：打印片段与落盘 hook 的唯一正本）
+ *
+ * 三道决定都写在这段正文里，不再由代码补：
+ * - **整仓全量**：`check` 不带 `--staged`，加一道 `validate`——它拦的是
+ *   `git commit --no-verify` 绕过 pre-commit 的内容，重复是设计使然；
+ * - **不做增量**：不解析 pre-push 从 stdin 收到的 `<local_ref> <local_oid>
+ *   <remote_ref> <remote_oid>` 清单，无论推什么整仓过一遍；子进程也不给它读；
+ * - **不内建逃生机制**：没有环境变量开关、没有超时、没有「慢则降级」，
+ *   唯一的口子是 git 原生 `git push --no-verify`。
+ */
+exports.PRE_PUSH_SNIPPET = `
+echo "🔍 Running harness pre-push checks (whole repo)..."
+
+# 分工：pre-commit 查暂存的（增量、快反馈），pre-push 查整仓的（全量、兜底）。
+# 同一次改动跑两遍是设计使然——这道拦的是 git commit --no-verify 绕出去的内容。
+# 本地 hook 只是自检与提醒，真正的门禁在服务端 CI；逃生口只有 git 原生 push --no-verify。
+# 不解析 pre-push 从 stdin 收到的 ref 清单，子进程一律不给它读（< /dev/null）。
+npx @dommaker/harness check < /dev/null
+if [ $? -ne 0 ]; then
+  echo "❌ Iron law check failed"
+  exit 1
+fi
+
+npx @dommaker/harness validate < /dev/null
+if [ $? -ne 0 ]; then
+  echo "❌ Validate failed"
+  exit 1
+fi
+
+echo "✅ All pre-push checks passed"
+`;
+/** 落盘的 pre-push hook = shebang + 说明行 + 共享片段 */
+function renderPrePushHook() {
+    return `#!/bin/sh
+# Harness pre-push hook
+${exports.PRE_PUSH_SNIPPET}`;
+}
+// ── GitLab CI（harness#143）：与 GH 版对仗的接线形状 ──────────────────────
+/**
+ * GitLab 任务的触发条件（决议 ⑥：用 `rules:` 不用过时的 `only:`）
+ *
+ * MR 事件 + main/master 分支 push，与 GH 版 `on:` 段一一对应。三个任务各自带一份
+ * ——GitLab 的 `default:` 不支持 `rules`，自建实例版本参差，不赌语法糖。
+ */
+const GITLAB_RULES = `  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "master"
+`;
+/** `.gitlab-ci.yml` 文件头：harness 只拥有其下的 `harness-*` 任务 */
+const GITLAB_CI_HEADER = `# 由 harness init 生成 —— 以下 harness-* 任务是 harness 的 CI 接线
+# 门禁真正生效还需在 GitLab 侧开分支保护：pipeline 成功才允许合并
+
+image: node:20
+
+stages:
+  - test
+
+`;
+/** GitLab harness-check 任务（`--print-snippets` 打印的 job 片段即此份） */
+exports.GITLAB_CI_SNIPPET = `harness-check:
+  stage: test
+  script:
+    - npm ci
+    - npx @dommaker/harness check
+    - npx @dommaker/harness validate
+    - npx @dommaker/harness passes-gate
+${GITLAB_RULES}`;
+/** harness 拥有的 GitLab 任务全集（治理档在场时含治理任务）——落盘正文与冲突片段共用 */
+function renderGitLabCiJobs(governanceLevel) {
+    return governanceLevel
+        ? `${exports.GITLAB_CI_SNIPPET}\n${renderGovernanceWorkflow(governanceLevel, 'gitlab')}`
+        : exports.GITLAB_CI_SNIPPET;
+}
+/** `.gitlab-ci.yml` 落盘全文正本（= 文件头 + harness 拥有的任务） */
+function renderGitLabCiFile(governanceLevel) {
+    return `${GITLAB_CI_HEADER}${renderGitLabCiJobs(governanceLevel)}`;
+}
+/** harness-check.yml 全文（落盘正文，冲突时打印的也是这一份） */
+exports.HARNESS_CHECK_WORKFLOW = `name: Harness Check
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  harness-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run harness check
+        run: npx @dommaker/harness check
+
+      - name: Run harness validate
+        run: npx @dommaker/harness validate
+
+      - name: Run harness passes-gate
+        run: npx @dommaker/harness passes-gate
+`;
+/**
+ * GitHub Actions job 片段（`init --print-snippets` 的片段视图，harness#153）
+ *
+ * 由上面的落盘正本裁出 `jobs:` 段之后的一切，**不是第二份手抄文本**——它曾独立存在并
+ * 少掉 `validate` / `passes-gate` 两道门禁，照抄的用户拿到比同版本 `harness init` 弱一半
+ * 的 CI（#103 判据的第三种形态）。形状与 GitLab 侧对仗：打印的是正本的 job 段。
+ */
+exports.GITHUB_ACTIONS_SNIPPET = exports.HARNESS_CHECK_WORKFLOW.slice(exports.HARNESS_CHECK_WORKFLOW.indexOf('  harness-check:'));
+/**
+ * 治理 CI 面正文
+ *
+ * `minimal` 档不带 docs 新鲜度检查（其余档位带，且失败不阻断）。平台只改变接线形状，
+ * 三条命令与档位语义一致（harness#143）：GitLab 侧的「失败不阻断」= `allow_failure: true`，
+ * 且因每个任务都是全新容器，docs 检查单列一个任务而非 GH 的一个 step。
+ */
+function renderGovernanceWorkflow(level, platform) {
+    if (platform === 'gitlab') {
+        const docsJob = level === 'minimal'
+            ? ''
+            : `
+harness-docs-freshness:
+  stage: test
+  script:
+    - npm ci
+    - npx @dommaker/harness sync-docs --check
+${GITLAB_RULES}  allow_failure: true
+`;
+        return `harness-governance:
+  stage: test
+  script:
+    - npm ci
+    - npx @dommaker/harness check
+    - npx @dommaker/harness passes-gate
+${GITLAB_RULES}${docsJob}`;
+    }
+    const docsCheckStep = level !== 'minimal'
+        ? `
+      - name: Check docs freshness
+        run: npx @dommaker/harness sync-docs --check
+        continue-on-error: true`
+        : '';
+    return `name: Harness Governance
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Constraint check
+        run: npx @dommaker/harness check
+
+      - name: Quality gate
+        run: npx @dommaker/harness passes-gate
+${docsCheckStep}
+`;
+}
+/** custom-constraints.yml 示例正文 */
+exports.CUSTOM_CONSTRAINTS_TEMPLATE = `# 自定义约束配置
+#
+# 此文件定义项目特定的约束，扩展或覆盖 harness 内置约束
+
+# ========================================
+# 自定义约束示例
+# ========================================
+
+custom_constraints:
+  # 示例 1：禁止 console.log
+  # my_project_no_console_log:
+  #   id: my_project_no_console_log
+  #   level: guideline
+  #   rule: "NO CONSOLE.LOG IN PRODUCTION CODE"
+  #   message: "生产代码禁止使用 console.log，请使用 logger 模块"
+  #   trigger: ["code_implementation"]
+  #   description: "使用项目统一的 logger 模块代替 console.log"
+
+  # 示例 2：禁止特定的导入
+  # my_project_no_moment_js:
+  #   id: my_project_no_moment_js
+  #   level: guideline
+  #   rule: "NO MOMENT.JS IMPORTS"
+  #   message: "禁止使用 moment.js，请使用 date-fns 或 dayjs"
+  #   trigger: ["code_implementation"]
+
+  # 示例 3：要求特定的文件命名
+  # my_project_component_naming:
+  #   id: my_project_component_naming
+  #   level: tip
+  #   rule: "REACT COMPONENTS SHOULD BE PASCAL CASE"
+  #   message: "React 组件文件名应使用 PascalCase"
+  #   trigger: ["file_creation"]
+`;
+/** CHANGELOG.md 正文（`format` 来自治理配置的 changelog.format） */
+function renderChangelog(format) {
+    return format === 'keep-a-changelog'
+        ? `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project setup with harness governance
+
+---
+
+> 此文件可由 \`harness sync-docs\` 辅助维护
+`
+        : `# Changelog
+
+## [Unreleased]
+
+- Initial project setup with harness governance
+
+---
+
+> 此文件可由 \`harness sync-docs\` 辅助维护
+`;
+}
+/** 目录 CONTEXT.md 骨架正文（`dir` 是相对项目根的目录路径） */
+function renderContextDoc(dir) {
+    const dirName = path.basename(dir);
+    return `# ${dirName}
+
+> 此文件描述 ${dir} 目录的职责和上下文
+> 请阅读本目录的源代码，然后填写以下各节。
+> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。
+
+## 职责
+
+<!-- 本目录的核心职责是什么 -->
+
+## 核心导出
+
+<!-- 本目录对外暴露的主要模块/函数 -->
+
+## 依赖关系
+
+<!-- 本目录依赖哪些其他模块，谁依赖本目录 -->
+
+## 注意事项
+
+<!-- 开发时需要注意的约束或约定 -->
+`;
+}
+/**
+ * 默认检查点列表
+ *
+ * 注：no-console 检查点已移除（工单 23/24）——CLI 产品 src/ 必然有合法 console 输出，
+ * 且旧配置 expected:'' 语义恒错；output_* 族修复为真正执行 config.command 后该检查会恒失败。
+ */
+exports.DEFAULT_CHECKPOINTS = [
+    {
+        id: 'build-success',
+        name: '构建成功',
+        checks: [
+            {
+                id: 'build-command',
+                type: 'command_success',
+                config: { command: 'npm run build' },
+                message: '构建命令必须成功执行',
+            },
+        ],
+    },
+    {
+        id: 'test-pass',
+        name: '测试通过',
+        checks: [
+            {
+                id: 'test-command',
+                type: 'command_success',
+                config: { command: 'npm test' },
+                message: '测试命令必须成功执行',
+            },
+        ],
+    },
+];
+/** 检查点文件的相对路径约定（validate 的缺省读取面与 init 的落盘面同一处） */
+exports.DEFAULT_CHECKPOINT_FILE = '.harness/checkpoints.yml';
+/** checkpoints.yml 正文 */
+function renderCheckpoints() {
+    return yaml.dump({ checkpoints: exports.DEFAULT_CHECKPOINTS }, { indent: 2 });
+}
+/** 默认 Resolutions（RKB — 约束 → 已知解法映射） */
+const DEFAULT_RESOLUTIONS = {
+    no_fuzzy_completion_claim: {
+        title: 'commit message 缺少验证证据',
+        fix: '在 commit message body 中附上验证输出:\n`npx @dommaker/harness check --staged` | `npx @dommaker/harness validate` | `npm test -- --coverage`\n确认全部通过后重新 commit。',
+    },
+    capability_sync: {
+        title: '缺少 CAPABILITIES.md',
+        fix: '在项目根目录创建 CAPABILITIES.md，列出所有模块能力清单。运行 `npx @dommaker/harness sync-docs` 可自动生成模板。',
+    },
+    context_doc_sync: {
+        title: '关键目录缺少 CONTEXT.md',
+        fix: '在 required_dirs 目录下创建 CONTEXT.md。运行 `npx @dommaker/harness sync-docs` 可自动生成模板。',
+    },
+};
+/** resolutions.json 正文 */
+function renderResolutions() {
+    return JSON.stringify(DEFAULT_RESOLUTIONS, null, 2);
+}
+//# sourceMappingURL=scaffold-templates.js.map

package/dist/cli/commands/scaffold-templates.js.map

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

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

@@ -0,0 +1,105 @@
+/**
+ * 脚手架落盘模块（harness#132，架构评审候选3）
+ *
+ * 一个决策只写一次：受管文件（managed file — harness 模板拥有正本、用户也可能
+ * 持有的落盘文件）在不在场、在场时算跳过还是算请用户手工合并、要不要建父目录、
+ * 打什么颜色的哪句话，全部收在本模块。此前这段判定复印在 init 6 处 + validate 2 处。
+ *
+ * 三态：
+ * - `created` 不在场 → 落盘模板正文
+ * - `exists`  在场 → 灰字告知跳过（**不细分内容是否等于模板**，内容比较是独立特性）
+ * - `manual`  在场 → 打印片段请用户手工合并
+ *
+ * 纪律：本模块不持有覆盖/跳过策略——「哪些文件要落」由命令层翻成 plan 列表传进来，
+ * 本模块只见 plan；模板正文住在 `scaffold-templates.ts`。
+ */
+import type { CiPlatform } from '../../types/project-config';
+import { type CommandIO } from '../command-contract';
+/** 三态判定结果 */
+export type ScaffoldOutcome = 'created' | 'exists' | 'manual';
+/**
+ * 落盘注入面（缺省 node fs；测试注入内存替身即可断言「真写出了什么内容」）
+ */
+export interface ScaffoldFileSystem {
+    exists(target: string): Promise<boolean>;
+    mkdir(dir: string): Promise<void>;
+    writeFile(target: string, content: string): Promise<void>;
+    chmod(target: string, mode: number): Promise<void>;
+}
+export declare const nodeScaffoldFs: ScaffoldFileSystem;
+/**
+ * 在场处置：
+ * - `skip`  harness 不再主张这份正文，灰字告知即可
+ * - `merge` 用户可能持有自己的内容，打印片段（与落盘正文同源）请其手工合并
+ */
+export type OnPresent = {
+    outcome: 'skip';
+    notice: string;
+} | {
+    outcome: 'merge';
+    notice: string;
+    /** 提示与指引之间的灰字补充行（如冲突来源清单） */
+    detail?: string[];
+    instruction: string;
+    snippet: string;
+};
+/** 一个受管文件 = 三态判定所需的全部数据 */
+export interface ManagedFile {
+    /** 落盘目标（绝对路径） */
+    target: string;
+    /** harness 拥有的模板正文 */
+    content: string;
+    /** 落盘态绿字 */
+    created: string;
+    /** 在场态处置 */
+    onPresent: OnPresent;
+    /** 在场判定覆写，缺省 = target 自身在场（冲突面可以宽于 target，如 CI 配置目录） */
+    present?: () => Promise<boolean>;
+    /** 落盘权限位（Git hook 需要可执行位） */
+    mode?: number;
+}
+/**
+ * 落一个受管文件：判定 → 建目录 → 写盘 → 上色打印
+ */
+export declare function writeManagedFile(file: ManagedFile, io: CommandIO, fs?: ScaffoldFileSystem): Promise<ScaffoldOutcome>;
+/** 按顺序落一组受管文件 */
+export declare function runPlan(plan: readonly ManagedFile[], io: CommandIO, fs?: ScaffoldFileSystem): Promise<ScaffoldOutcome[]>;
+/** .git/hooks/pre-commit（冲突片段 = 落盘正文去掉 shebang 头，逐字同源） */
+export declare function preCommitHookFile(projectPath: string): ManagedFile;
+/**
+ * .git/hooks/pre-push（harness#144 的第 9 站点，冲突片段与落盘正文逐字同源）
+ *
+ * 与 pre-commit 的分工：那道查暂存的（增量、快反馈），这道查整仓的（全量、兜底）。
+ * 本地 hook 是自检与提醒，门禁真正的落点仍是服务端 CI。
+ */
+export declare function prePushHookFile(projectPath: string): ManagedFile;
+/**
+ * 服务端 CI 门禁站点（平台维度，harness#143）
+ *
+ * - `github` → `.github/workflows/harness-check.yml`；冲突判定宽于 target 自身：
+ *   工作流目录里已有任何 CI 配置就算冲突，片段是完整 workflow 正文（打印的即落盘的，#103 判据）
+ * - `gitlab` → `.gitlab-ci.yml`；冲突面就是该文件自身在场，片段是 harness 拥有的任务正文。
+ *   GitLab 没有「第二个 CI 文件位」，所以 `-g` 档的治理任务并入同一份正文
+ *   ——这也是 `governanceLevel` 只对 gitlab 形有意义的原因（GH 侧治理站是独立的
+ *   `governanceWorkflowFile`）。
+ *
+ * `none`（不接线）不进来：那是命令层的 plan 里没有这个站点，scaffold 不持有跳过策略。
+ */
+export declare function harnessCheckCiFile(projectPath: string, platform: CiPlatform, existingCiWorkflows: string[], governanceLevel?: string): ManagedFile;
+/** .harness/custom-constraints.yml 示例 */
+export declare function customConstraintsFile(projectPath: string): ManagedFile;
+/** .harness/checkpoints.yml 示例（原住 validate.ts，路径约定与 validate 共用） */
+export declare function checkpointsFile(projectPath: string): ManagedFile;
+/** .harness/resolutions.json（RKB 狗粮 — 约束 → 已知解法映射，原住 validate.ts） */
+export declare function resolutionsFile(projectPath: string): ManagedFile;
+/** CHANGELOG.md 骨架 */
+export declare function changelogFile(projectPath: string, format: string): ManagedFile;
+/** `<dir>/CONTEXT.md` 骨架 */
+export declare function contextDocFile(projectPath: string, dir: string): ManagedFile;
+/**
+ * .github/workflows/harness-governance.yml（治理 CI 面，仅 github 形）
+ *
+ * gitlab 形的治理任务并入 `.gitlab-ci.yml`（见 `harnessCheckCiFile`），无本站点。
+ */
+export declare function governanceWorkflowFile(projectPath: string, level: string): ManagedFile;
+//# sourceMappingURL=scaffold.d.ts.map

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

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