svharness 0.8.0 → 0.13.2

package/dist/config/normalize.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfigHarnessName = resolveConfigHarnessName;
+exports.normalizeConfig = normalizeConfig;
+const logger_1 = require("../utils/logger");
+const constants_1 = require("./constants");
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function normalizeStringArray(v, field) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (Array.isArray(v)) {
+        return v.map((x) => String(x).trim()).filter(Boolean);
+    }
+    if (typeof v === 'string' && v.trim())
+        return [v.trim()];
+    throw new Error(`配置字段 ${field} 必须是字符串或字符串数组`);
+}
+/**
+ * Resolve harnessName vs legacy `name`; error if both differ.
+ */
+function resolveConfigHarnessName(section) {
+    const hn = section.harnessName?.trim();
+    const legacy = section.name?.trim();
+    if (hn && legacy && hn !== legacy) {
+        throw new Error('配置 build 中 harnessName 与 name 取值不同，请只保留 harnessName');
+    }
+    if (hn)
+        return hn;
+    if (legacy) {
+        logger_1.logger.warn('⚠️  配置 build.name 已重命名为 harnessName，旧键将在下个 minor 版本移除。');
+        return legacy;
+    }
+    return undefined;
+}
+function pickBuildSection(raw) {
+    const s = {};
+    const str = (k) => {
+        const v = raw[k];
+        if (v !== undefined && v !== null)
+            s[k] = String(v).trim();
+    };
+    str('harnessName');
+    str('name');
+    str('arch');
+    str('agent');
+    str('baseline');
+    str('requirements');
+    str('requirementsNote');
+    str('references');
+    str('referencesNote');
+    str('extraSkillsNote');
+    str('baselineBranch');
+    str('convertEndpoint');
+    str('wikiLang');
+    str('wikiModel');
+    str('wikiBaseUrl');
+    str('wikiApiKey');
+    str('wikiSource');
+    if (raw.baselineMaxFileKb !== undefined) {
+        s.baselineMaxFileKb = Number(raw.baselineMaxFileKb);
+    }
+    for (const k of ['convertConcurrency', 'convertMaxFileMb', 'convertTimeoutSec']) {
+        if (raw[k] !== undefined) {
+            s[k] = Number(raw[k]);
+        }
+    }
+    for (const k of [
+        'convertForce',
+        'force',
+        'yes',
+        'verbose',
+        'generateWiki',
+        'wikiTasksOnly',
+    ]) {
+        if (raw[k] !== undefined)
+            s[k] = Boolean(raw[k]);
+    }
+    const extra = normalizeStringArray(raw.extraSkills, 'build.extraSkills');
+    if (extra)
+        s.extraSkills = extra;
+    return s;
+}
+function pickApplySection(raw) {
+    const s = {};
+    for (const k of ['harness', 'target', 'agent']) {
+        if (raw[k] !== undefined && raw[k] !== null)
+            s[k] = String(raw[k]).trim();
+    }
+    for (const k of ['force', 'clone', 'yes', 'verbose']) {
+        if (raw[k] !== undefined)
+            s[k] = Boolean(raw[k]);
+    }
+    return s;
+}
+function pickConvertSection(raw) {
+    const s = {};
+    const input = normalizeStringArray(raw.input, 'convert.input');
+    if (input)
+        s.input = input;
+    for (const k of ['harness', 'output', 'endpoint', 'type']) {
+        if (raw[k] !== undefined && raw[k] !== null)
+            s[k] = String(raw[k]).trim();
+    }
+    for (const k of ['concurrency', 'maxFileMb', 'timeoutSec']) {
+        if (raw[k] !== undefined)
+            s[k] = Number(raw[k]);
+    }
+    for (const k of ['force', 'yes', 'verbose']) {
+        if (raw[k] !== undefined)
+            s[k] = Boolean(raw[k]);
+    }
+    return s;
+}
+function pickDefaults(raw) {
+    const s = {};
+    if (raw.arch !== undefined)
+        s.arch = String(raw.arch).trim();
+    if (raw.agent !== undefined)
+        s.agent = String(raw.agent).trim();
+    for (const k of ['yes', 'verbose', 'force']) {
+        if (raw[k] !== undefined)
+            s[k] = Boolean(raw[k]);
+    }
+    return s;
+}
+/**
+ * Parse and normalize raw YAML/JSON object into SvharnessConfig.
+ */
+function normalizeConfig(raw, configPath) {
+    if (!isPlainObject(raw)) {
+        throw new Error(`配置文件格式无效（需为对象）：${configPath}`);
+    }
+    const version = raw.version;
+    if (version !== undefined && version !== constants_1.CONFIG_SCHEMA_VERSION) {
+        throw new Error(`不支持的配置 version: ${version}（当前仅支持 ${constants_1.CONFIG_SCHEMA_VERSION}）`);
+    }
+    const cfg = { version: constants_1.CONFIG_SCHEMA_VERSION };
+    if (raw.defaults !== undefined) {
+        if (!isPlainObject(raw.defaults)) {
+            throw new Error(`配置 defaults 必须是对象：${configPath}`);
+        }
+        cfg.defaults = pickDefaults(raw.defaults);
+    }
+    if (raw.build !== undefined) {
+        if (!isPlainObject(raw.build)) {
+            throw new Error(`配置 build 必须是对象：${configPath}`);
+        }
+        cfg.build = pickBuildSection(raw.build);
+    }
+    if (raw.apply !== undefined) {
+        if (!isPlainObject(raw.apply)) {
+            throw new Error(`配置 apply 必须是对象：${configPath}`);
+        }
+        cfg.apply = pickApplySection(raw.apply);
+    }
+    if (raw.convert !== undefined) {
+        if (!isPlainObject(raw.convert)) {
+            throw new Error(`配置 convert 必须是对象：${configPath}`);
+        }
+        cfg.convert = pickConvertSection(raw.convert);
+    }
+    return cfg;
+}

package/dist/config/save-config.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveConfigSection = saveConfigSection;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const constants_1 = require("./constants");
+/**
+ * Write or merge a command section into svharness.config.yaml.
+ */
+async function saveConfigSection(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const outPath = node_path_1.default.resolve(options.outPath ?? node_path_1.default.join(cwd, constants_1.DEFAULT_CONFIG_FILENAME));
+    let existing = { version: constants_1.CONFIG_SCHEMA_VERSION };
+    if (await fs_extra_1.default.pathExists(outPath)) {
+        const raw = js_yaml_1.default.load(await fs_extra_1.default.readFile(outPath, 'utf8'));
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            existing = { version: constants_1.CONFIG_SCHEMA_VERSION, ...raw };
+        }
+    }
+    if (options.build) {
+        existing.build = { ...existing.build, ...options.build };
+    }
+    if (options.apply) {
+        existing.apply = { ...existing.apply, ...options.apply };
+    }
+    if (options.convert) {
+        existing.convert = { ...existing.convert, ...options.convert };
+    }
+    existing.version = constants_1.CONFIG_SCHEMA_VERSION;
+    const body = '# svharness 配置文件 —— 由 wizard 或 --save-config 生成\n' +
+        '# 优先级：CLI 参数 > 本文件 > 代码默认值\n' +
+        js_yaml_1.default.dump(existing, { lineWidth: 100, noRefs: true });
+    await fs_extra_1.default.ensureDir(node_path_1.default.dirname(outPath));
+    await fs_extra_1.default.writeFile(outPath, body, 'utf8');
+    return outPath;
+}

package/dist/config/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/agent-injector.js

@@ -8,13 +8,50 @@ exports.injectSkillsLayered = injectSkillsLayered;
 exports.injectRulesLayered = injectRulesLayered;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
 const logger_1 = require("../utils/logger");
+const BINDING_PLACEHOLDER = '{{BINDING_YAML_BLOCK}}';
 const BUILD_SKILLS = [
+    'harness-build-skills-main.md',
     'harness-build-skill-orchestrator.md',
     'harness-build-skill-spec-builder.md',
+    'harness-build-skill-references-intake.md',
+    'harness-build-skill-agent-env-merge.md',
     'harness-build-skill-knowledge-builder.md',
     'harness-build-skill-wiki-writer.md',
 ];
+function buildSkillsBindingYaml(input, adapter) {
+    const harness_root_rel = `./${input.harnessDirName.replace(/\\/g, '/')}/`;
+    const obj = {
+        harness_root_rel,
+        harness_name: input.harnessName,
+        arch: input.arch,
+        agent: input.agent,
+        build_rules_dir: adapter.rulesDir ?? '',
+        build_skills_dir: adapter.skillsDir,
+        generated_at: input.generatedAt,
+        generated_by: `svharness@${input.cliVersion}`,
+    };
+    return js_yaml_1.default.dump(obj, { lineWidth: 120, noRefs: true }).trimEnd();
+}
+function applyBuildSkillReplacements(raw, adapter, harnessPrefix, opts) {
+    let s = raw.replace(/__HARNESS_ROOT__/g, harnessPrefix);
+    s = s.replace(/__HARNESS_BUILD_RULES_DIR__/g, adapter.rulesDir ?? '');
+    s = s.replace(/__HARNESS_BUILD_SKILLS_DIR__/g, adapter.skillsDir);
+    if (opts.srcName === 'harness-build-skills-main.md') {
+        if (!opts.binding) {
+            throw new Error('harness-build-skills-main.md requires BuildSkillsBindingInput (use injectSkillsLayered with binding)');
+        }
+        if (!s.includes(BINDING_PLACEHOLDER)) {
+            throw new Error(`harness-build-skills-main.md template missing ${BINDING_PLACEHOLDER}`);
+        }
+        s = s.replace(BINDING_PLACEHOLDER, buildSkillsBindingYaml(opts.binding, adapter));
+    }
+    else if (s.includes(BINDING_PLACEHOLDER)) {
+        throw new Error(`unexpected ${BINDING_PLACEHOLDER} in ${opts.srcName}`);
+    }
+    return s;
+}
 /**
  * Copy build-helper skills into the target project's agent skills directory,
  * transforming content via the adapter when needed.
@@ -28,25 +65,35 @@ const BUILD_SKILLS = [
  * @param skillsRoot    Base directory for the agent skills folder.
  *                      Defaults to targetRoot (legacy). Pass cwd to inject
  *                      beside the harness folder instead of inside it.
+ * @param binding        Metadata for `harness-build-skills-main` (inlined YAML).
  */
-async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot) {
+async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot, binding) {
     if (!(await fs_extra_1.default.pathExists(skillsSrcDir))) {
         throw new Error(`build-skills source directory missing: ${skillsSrcDir}`);
     }
     const base = skillsRoot ?? targetRoot;
     const dstDir = node_path_1.default.join(base, adapter.skillsDir);
     await fs_extra_1.default.ensureDir(dstDir);
+    const harnessPrefix = `./${node_path_1.default.basename(targetRoot)}/`;
     const injected = [];
     for (const srcName of BUILD_SKILLS) {
+        if (srcName === 'harness-build-skills-main.md' && !binding) {
+            logger_1.logger.debug('skip harness-build-skills-main.md: injectSkills called without binding context');
+            continue;
+        }
         const srcPath = node_path_1.default.join(skillsSrcDir, srcName);
         if (!(await fs_extra_1.default.pathExists(srcPath))) {
             logger_1.logger.warn(`build-skill missing, skipped: ${srcName}`);
             continue;
         }
         const raw = await fs_extra_1.default.readFile(srcPath, 'utf8');
+        const withPlaceholders = applyBuildSkillReplacements(raw, adapter, harnessPrefix, {
+            srcName,
+            binding,
+        });
         const content = adapter.transform
-            ? adapter.transform(raw, srcName)
-            : raw;
+            ? adapter.transform(withPlaceholders, srcName)
+            : withPlaceholders;
         const baseName = srcName.replace(/\.md$/, '');
         // Each skill lives in its own subdirectory named after the skill,
         // with the content file always named SKILL<ext> (e.g. SKILL.md).
@@ -77,10 +124,10 @@ async function injectSkills(skillsSrcDir, targetRoot, adapter, skillsRoot) {
  * @param skillsRoot     Base directory for the agent skills folder.
  *                       Defaults to targetRoot (legacy). Pass cwd to inject
  *                       beside the harness folder instead of inside it.
- * @param harnessDirName Directory name of the harness (e.g. `demo8-harness`).
- *                       Used to replace `__HARNESS_ROOT__` in skill content.
+ * @param binding        Metadata for `__HARNESS_ROOT__` and inlined YAML in
+ *                        `harness-build-skills-main` (`harnessDirName` inside binding).
  */
-async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoot, harnessDirName) {
+async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoot, binding) {
     const existing = [];
     for (const d of skillsSrcDirs) {
         if (await fs_extra_1.default.pathExists(d))
@@ -92,7 +139,6 @@ async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoo
     const base = skillsRoot ?? targetRoot;
     const dstDir = node_path_1.default.join(base, adapter.skillsDir);
     await fs_extra_1.default.ensureDir(dstDir);
-    const harnessPrefix = harnessDirName ? `./${harnessDirName}/` : './';
     const injected = [];
     for (const srcName of BUILD_SKILLS) {
         let picked = null;
@@ -108,8 +154,11 @@ async function injectSkillsLayered(skillsSrcDirs, targetRoot, adapter, skillsRoo
             continue;
         }
         const raw = await fs_extra_1.default.readFile(picked, 'utf8');
-        // Replace harness root placeholder with the actual harness directory
-        const resolved = raw.replace(/__HARNESS_ROOT__/g, harnessPrefix);
+        const harnessPrefix = `./${binding.harnessDirName.replace(/\\/g, '/')}/`;
+        const resolved = applyBuildSkillReplacements(raw, adapter, harnessPrefix, {
+            srcName,
+            binding,
+        });
         const content = adapter.transform
             ? adapter.transform(resolved, srcName)
             : resolved;

package/dist/core/apply-project-entry.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeApplyProjectEntry = writeApplyProjectEntry;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../utils/logger");
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+function toHarnessScopedRef(raw, harnessDirName) {
+    const ref = toPosix(raw.trim());
+    if (ref.startsWith('http://') ||
+        ref.startsWith('https://') ||
+        ref.startsWith('mailto:') ||
+        ref.startsWith('#')) {
+        return raw;
+    }
+    const normalized = ref.replace(/^\.\//, '');
+    const coreMatch = /^(agent-env|baseline|specs|references|tasks)\//.test(normalized) ||
+        /^(harness\.yaml|VERSION|\.harness-build-state\.yaml|AGENTS_BUILD\.md|AGENTS_APPLY\.md)$/.test(normalized);
+    if (!coreMatch)
+        return raw;
+    return `./${harnessDirName}/${normalized}`;
+}
+function rewriteEntryReferences(content, harnessDirName) {
+    const withMarkdownLinks = content.replace(/\]\(([^)]+)\)/g, (_m, linkTarget) => {
+        const [pathPart, ...rest] = linkTarget.split('#');
+        const rewritten = toHarnessScopedRef(pathPart, harnessDirName);
+        if (rest.length > 0) {
+            return `](${rewritten}#${rest.join('#')})`;
+        }
+        return `](${rewritten})`;
+    });
+    return withMarkdownLinks.replace(/`([^`\n]+)`/g, (_m, token) => {
+        return `\`${toHarnessScopedRef(token, harnessDirName)}\``;
+    });
+}
+/**
+ * Write `AGENTS.md` or `CLAUDE.md` at the target project root by copying
+ * `<harness>/AGENTS_APPLY.md` and renaming it to the adapter's entry file.
+ *
+ * @returns relative path written, or undefined when skipped
+ */
+async function writeApplyProjectEntry(input) {
+    const src = node_path_1.default.join(input.harnessRoot, 'AGENTS_APPLY.md');
+    if (!(await fs_extra_1.default.pathExists(src))) {
+        throw new Error(`harness 中缺少 AGENTS_APPLY.md：${src}\n  请先重新执行 svharness build 生成应用指南。`);
+    }
+    const fileName = input.adapter.projectEntryFile;
+    const dest = node_path_1.default.join(input.projectRoot, fileName);
+    const rel = fileName;
+    if (await fs_extra_1.default.pathExists(dest)) {
+        if (!input.force) {
+            logger_1.logger.warn(`项目根已存在 ${rel}，跳过写入（如需覆盖请使用 svharness apply --force）`);
+            return undefined;
+        }
+    }
+    const raw = await fs_extra_1.default.readFile(src, 'utf8');
+    const rewritten = rewriteEntryReferences(raw, input.harnessDirName);
+    await fs_extra_1.default.outputFile(dest, rewritten, 'utf8');
+    logger_1.logger.success(`已写入项目根 AI 入口：${rel}（由 AGENTS_APPLY.md 重命名）`);
+    return rel;
+}

package/dist/core/build-project-entry.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderBuildProjectEntryMarkdown = renderBuildProjectEntryMarkdown;
+exports.writeBuildProjectEntry = writeBuildProjectEntry;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../utils/logger");
+function entryHeading(projectEntryFile) {
+    if (projectEntryFile === 'CLAUDE.md') {
+        return '# CLAUDE.md';
+    }
+    return '# AGENTS.md';
+}
+/**
+ * Render the markdown body for the project-root AI entry file
+ * (`AGENTS.md` or `CLAUDE.md`) created by `svharness build`.
+ */
+function renderBuildProjectEntryMarkdown(input) {
+    const relHarness = `./${input.harnessDirName.replace(/\\/g, '/')}/`;
+    const relAgentsBuild = `${relHarness}AGENTS_BUILD.md`.replace(/\/+/g, '/');
+    const rulesLine = input.adapter.rulesDir
+        ? `- **构建规则（强约束）**：\`${input.adapter.rulesDir}/\`（harness-build-rule-*）`
+        : '- **构建规则**：本 Agent 未配置 rules 注入目录（跳过）';
+    const title = entryHeading(input.adapter.projectEntryFile);
+    return [
+        title,
+        '',
+        '> 本文件由 `svharness build` 根据所选 Agent 自动生成，用于指引 AI **载入整个 harness-build 工作流**。',
+        '> 若内容与你的习惯冲突，可改 harness 内契约后重新执行 `svharness build --force` 覆盖本文件。',
+        '',
+        '## 1. 必读（harness 内）',
+        '',
+        `1. **Harness 根目录（相对项目根）**：\`${relHarness}\``,
+        `2. **协作协议**：[\`AGENTS_BUILD.md\`](${relAgentsBuild})`,
+        `3. **状态机**：\`${relHarness}.harness-build-state.yaml\``,
+        `4. **清单**：\`${relHarness}harness.yaml\``,
+        '',
+        '## 2. harness-build 总清单 skill（二级调度，优先入口）',
+        '',
+        '在支持 skill 的 Agent IDE 中，**优先**加载并触发：',
+        '',
+        `- **\`harness-build-skills-main\`** — 解析 skill 内「绑定元数据」→ 装载构建规则 → 路由到 orchestrator / spec-builder / references-intake / agent-env-merge / knowledge-builder / wiki-writer。`,
+        `- 磁盘路径（相对项目根）：\`${input.adapter.skillsDir}/harness-build-skills-main/\`（主文件名为 \`SKILL${input.adapter.skillExt}\`）`,
+        '',
+        '### 子 skill 速查',
+        '',
+        '| 子 skill | 用途 |',
+        '|----------|------|',
+        '| `harness-build-skill-orchestrator` | 阶段调度、更新 `.harness-build-state.yaml` |',
+        '| `harness-build-skill-spec-builder` | raw → requirements → specs |',
+        '| `harness-build-skill-references-intake` | S60 references 转换与结构化索引 |',
+        '| `harness-build-skill-agent-env-merge` | S61 baseline 自动提取确认 + S65 合并写入 |',
+        '| `harness-build-skill-knowledge-builder` | S10 baseline 样本 + S70 skills/tasks 索引 |',
+        '| `harness-build-skill-wiki-writer` | 按 `TASKS.md` 撰写 baseline wiki |',
+        '',
+        '## 3. 构建规则目录（与 harness 分离，位于项目根）',
+        '',
+        rulesLine,
+        '',
+        '## 4. 元数据（供人类核对）',
+        '',
+        `- harness 名称：\`${input.harnessName}\``,
+        `- 目录名：\`${input.harnessDirName}\``,
+        `- 架构：\`${input.arch}\``,
+        `- Agent：\`${input.agent}\``,
+        '',
+    ].join('\n');
+}
+/**
+ * Write `AGENTS.md` or `CLAUDE.md` at the project root when absent,
+ * or when `force` is true.
+ *
+ * @returns relative path written, or undefined when skipped
+ */
+async function writeBuildProjectEntry(input) {
+    const fileName = input.adapter.projectEntryFile;
+    const dest = node_path_1.default.join(input.projectRoot, fileName);
+    const rel = fileName;
+    if (await fs_extra_1.default.pathExists(dest)) {
+        if (!input.force) {
+            logger_1.logger.warn(`项目根已存在 ${rel}，跳过写入（如需覆盖请对 harness 使用 --force 并确保允许覆盖根入口文件）`);
+            return undefined;
+        }
+    }
+    const body = renderBuildProjectEntryMarkdown({
+        adapter: input.adapter,
+        harnessDirName: input.harnessDirName,
+        harnessName: input.harnessName,
+        arch: input.arch,
+        agent: input.agent,
+    });
+    await fs_extra_1.default.outputFile(dest, body, 'utf8');
+    logger_1.logger.success(`已写入项目根 AI 入口：${rel}`);
+    return rel;
+}

package/dist/core/doc-intake-paths.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAW_SKIP_DIR_NAMES = void 0;
+exports.shouldSkipRawSubdir = shouldSkipRawSubdir;
+exports.collectSeedSourceFiles = collectSeedSourceFiles;
+exports.copySeedInputToRaw = copySeedInputToRaw;
+exports.relocateMisplacedConvertedMd = relocateMisplacedConvertedMd;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Subdirs under `<type>/raw/` that must never be scanned or copied as source trees. */
+exports.RAW_SKIP_DIR_NAMES = new Set([
+    'converted_md',
+    'md',
+    'yaml',
+    'node_modules',
+    '.git',
+    'dist',
+]);
+function shouldSkipRawSubdir(name) {
+    return exports.RAW_SKIP_DIR_NAMES.has(name);
+}
+/**
+ * Recursively list source files for seed intake, skipping harness artifact dirs.
+ */
+async function collectSeedSourceFiles(rootDir) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await fs_extra_1.default.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === '.gitkeep')
+                continue;
+            const abs = node_path_1.default.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (shouldSkipRawSubdir(entry.name))
+                    continue;
+                await walk(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(abs);
+            }
+        }
+    }
+    await walk(rootDir);
+    return out.sort();
+}
+async function allocateFlatName(targetDir, baseName, used) {
+    if (!used.has(baseName) && !(await fs_extra_1.default.pathExists(node_path_1.default.join(targetDir, baseName)))) {
+        return baseName;
+    }
+    const ext = node_path_1.default.extname(baseName);
+    const stem = ext ? baseName.slice(0, -ext.length) : baseName;
+    for (let i = 1; i < 1000; i++) {
+        const next = ext ? `${stem}-${i}${ext}` : `${stem}-${i}`;
+        if (!used.has(next) && !(await fs_extra_1.default.pathExists(node_path_1.default.join(targetDir, next)))) {
+            return next;
+        }
+    }
+    throw new Error(`无法为 raw 目录分配唯一文件名: ${baseName}`);
+}
+/**
+ * Copy a file or directory of source documents into `<harness>/<type>/raw/` as a flat list.
+ * Nested legacy folders such as `assets/raw/converted_md/` are not preserved.
+ */
+async function copySeedInputToRaw(inputPath, rawDir, label) {
+    const absInput = node_path_1.default.resolve(inputPath);
+    if (!(await fs_extra_1.default.pathExists(absInput))) {
+        throw new Error(`${label} 输入路径不存在: ${absInput}`);
+    }
+    await fs_extra_1.default.ensureDir(rawDir);
+    const stat = await fs_extra_1.default.stat(absInput);
+    if (stat.isFile()) {
+        const dest = node_path_1.default.join(rawDir, node_path_1.default.basename(absInput));
+        await fs_extra_1.default.copy(absInput, dest, { overwrite: true, errorOnExist: false });
+        return 1;
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`${label} 输入路径必须是文件或目录: ${absInput}`);
+    }
+    const files = await collectSeedSourceFiles(absInput);
+    const used = new Set();
+    let copied = 0;
+    for (const file of files) {
+        const destName = await allocateFlatName(rawDir, node_path_1.default.basename(file), used);
+        used.add(destName);
+        await fs_extra_1.default.copy(file, node_path_1.default.join(rawDir, destName), {
+            overwrite: true,
+            errorOnExist: false,
+        });
+        copied += 1;
+    }
+    return copied;
+}
+/** Move misplaced converted_md markdown files under raw into harness type/md. */
+async function relocateMisplacedConvertedMd(harnessRoot, type) {
+    const rawDir = node_path_1.default.join(harnessRoot, type, 'raw');
+    const mdDir = node_path_1.default.join(harnessRoot, type, 'md');
+    if (!(await fs_extra_1.default.pathExists(rawDir)))
+        return 0;
+    await fs_extra_1.default.ensureDir(mdDir);
+    const misplaced = await findMisplacedConvertedMd(rawDir);
+    if (misplaced.length === 0)
+        return 0;
+    const used = new Set();
+    for (const abs of misplaced) {
+        const base = node_path_1.default.basename(abs);
+        const destName = await allocateFlatName(mdDir, base, used);
+        used.add(destName);
+        await fs_extra_1.default.move(abs, node_path_1.default.join(mdDir, destName), { overwrite: true });
+    }
+    await removeEmptyConvertedMdDirs(rawDir);
+    return misplaced.length;
+}
+async function findMisplacedConvertedMd(rawDir) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await fs_extra_1.default.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = node_path_1.default.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'converted_md') {
+                    for (const f of await fs_extra_1.default.readdir(abs)) {
+                        if (f.toLowerCase().endsWith('.md')) {
+                            out.push(node_path_1.default.join(abs, f));
+                        }
+                    }
+                    continue;
+                }
+                if (shouldSkipRawSubdir(entry.name))
+                    continue;
+                await walk(abs);
+            }
+        }
+    }
+    await walk(rawDir);
+    return out;
+}
+async function removeEmptyConvertedMdDirs(rawDir) {
+    async function walk(dir) {
+        const entries = await fs_extra_1.default.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const abs = node_path_1.default.join(dir, entry.name);
+            if (entry.name === 'converted_md') {
+                await fs_extra_1.default.remove(abs);
+                continue;
+            }
+            await walk(abs);
+        }
+    }
+    await walk(rawDir);
+}