novel-writer-cli 0.0.1

package/dist/__tests__/readability-lint.test.js

@@ -0,0 +1,209 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { parsePlatformProfile } from "../platform-profile.js";
+import { computeReadabilityReport, writeReadabilityLogs } from "../readability-lint.js";
+function makeProfileRaw(extra) {
+    return {
+        schema_version: 1,
+        platform: "qidian",
+        created_at: "2026-01-01T00:00:00Z",
+        word_count: { target_min: 1, target_max: 2, hard_min: 1, hard_max: 2 },
+        hook_policy: { required: false, min_strength: 3, allowed_types: ["question"], fix_strategy: "hook-fix" },
+        info_load: { max_new_entities_per_chapter: 0, max_unknown_entities_per_chapter: 0, max_new_terms_per_1k_words: 0 },
+        compliance: { banned_words: [], duplicate_name_policy: "warn" },
+        scoring: { genre_drive_type: "plot", weight_profile_id: "plot:v1" },
+        ...extra
+    };
+}
+function makeReadabilityPolicy(overrides = {}) {
+    return {
+        mobile: {
+            enabled: true,
+            max_paragraph_chars: 10,
+            max_consecutive_exposition_paragraphs: 2,
+            blocking_severity: "hard_only",
+            ...overrides
+        }
+    };
+}
+test("computeReadabilityReport skips when readability.mobile is missing/disabled", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-skip-test-"));
+    const profile = parsePlatformProfile(makeProfileRaw({ readability: null }), "platform-profile.json");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath: join(rootDir, "chapter.md"),
+        chapterText: "# T\n正文",
+        platformProfile: profile
+    });
+    assert.equal(report.status, "skipped");
+    assert.equal(report.issues.length, 0);
+});
+test("computeReadabilityReport fallback flags overlong paragraphs and mixed punctuation (warn-only)", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-fallback-test-"));
+    const profile = parsePlatformProfile(makeProfileRaw({ readability: makeReadabilityPolicy({ max_paragraph_chars: 5 }) }), "platform-profile.json");
+    const chapterText = '第一段太长太长太长, A. 但是用了全角，。\n\n第二段。';
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath: join(rootDir, "chapter.md"),
+        chapterText,
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "fallback");
+    assert.equal(report.has_blocking_issues, false);
+    assert.equal(report.status, "warn");
+    assert.ok(report.issues.some((i) => i.id === "readability.mobile.overlong_paragraph"));
+    assert.ok(report.issues.some((i) => i.id === "readability.mobile.mixed_comma_styles"));
+    assert.ok(report.issues.some((i) => i.id === "readability.mobile.mixed_period_styles"));
+});
+test("computeReadabilityReport uses deterministic script output and derives blocking status from policy", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-script-test-"));
+    await mkdir(join(rootDir, "scripts"), { recursive: true });
+    const profile = parsePlatformProfile(makeProfileRaw({
+        compliance: { banned_words: [], duplicate_name_policy: "warn", script_paths: { lint_readability: "scripts/lint-readability.sh" } },
+        readability: makeReadabilityPolicy({ blocking_severity: "soft_and_hard" })
+    }), "platform-profile.json");
+    await writeFile(join(rootDir, "platform-profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    const chapterAbsPath = join(rootDir, "chapter.md");
+    await writeFile(chapterAbsPath, "# T\n正文\n", "utf8");
+    const scriptAbs = join(rootDir, "scripts", "lint-readability.sh");
+    const stubJson = '{"schema_version":1,"generated_at":"2026-01-01T00:00:00.000Z","scope":{"chapter":1},"policy":{"enabled":true,"max_paragraph_chars":10,"max_consecutive_exposition_paragraphs":2,"blocking_severity":"soft_and_hard"},"issues":[{"id":"readability.mobile.overlong_paragraph","severity":"soft","summary":"Soft but blocking when configured."}]}';
+    const stubScript = `#!/usr/bin/env bash\nset -euo pipefail\nprintf '%s\\n' '${stubJson}'\n`;
+    await writeFile(scriptAbs, stubScript, "utf8");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath,
+        chapterText: "# T\n正文\n",
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "script");
+    assert.equal(report.has_blocking_issues, true);
+    assert.equal(report.status, "violation");
+});
+test("computeReadabilityReport trusts platform profile policy over script policy", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-policy-wins-test-"));
+    await mkdir(join(rootDir, "scripts"), { recursive: true });
+    const profile = parsePlatformProfile(makeProfileRaw({
+        compliance: { banned_words: [], duplicate_name_policy: "warn", script_paths: { lint_readability: "scripts/lint-readability.sh" } },
+        readability: makeReadabilityPolicy({ blocking_severity: "hard_only" })
+    }), "platform-profile.json");
+    await writeFile(join(rootDir, "platform-profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    const chapterAbsPath = join(rootDir, "chapter.md");
+    await writeFile(chapterAbsPath, "# T\n正文\n", "utf8");
+    const scriptAbs = join(rootDir, "scripts", "lint-readability.sh");
+    const stubJson = '{"schema_version":1,"generated_at":"2026-01-01T00:00:00.000Z","scope":{"chapter":1},"policy":{"enabled":true,"max_paragraph_chars":10,"max_consecutive_exposition_paragraphs":2,"blocking_severity":"soft_and_hard"},"issues":[{"id":"readability.mobile.overlong_paragraph","severity":"soft","summary":"Soft issue should not block when profile is hard_only."}]}';
+    const stubScript = `#!/usr/bin/env bash\nset -euo pipefail\nprintf '%s\\n' '${stubJson}'\n`;
+    await writeFile(scriptAbs, stubScript, "utf8");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath,
+        chapterText: "# T\n正文\n",
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "script");
+    assert.equal(report.policy?.blocking_severity, "hard_only");
+    assert.equal(report.has_blocking_issues, false);
+    assert.equal(report.status, "warn");
+});
+test("computeReadabilityReport falls back when lint_readability script path contains traversal segments", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-traversal-test-"));
+    const profile = parsePlatformProfile(makeProfileRaw({
+        compliance: { banned_words: [], duplicate_name_policy: "warn", script_paths: { lint_readability: "../evil.sh" } },
+        readability: makeReadabilityPolicy()
+    }), "platform-profile.json");
+    const chapterAbsPath = join(rootDir, "chapter.md");
+    await writeFile(chapterAbsPath, "# T\n正文\n", "utf8");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath,
+        chapterText: "# T\n正文\n",
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "fallback");
+    assert.ok(typeof report.script_error === "string" && report.script_error.includes("../evil.sh"));
+    assert.ok(typeof report.script_error === "string" && report.script_error.includes("must not contain '..'"));
+});
+test("computeReadabilityReport falls back when lint_readability script resolves outside project root (symlink)", async () => {
+    if (process.platform === "win32")
+        return;
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-symlink-test-"));
+    await mkdir(join(rootDir, "scripts"), { recursive: true });
+    const outsideDir = await mkdtemp(join(tmpdir(), "novel-readability-symlink-outside-"));
+    const outsideAbs = join(outsideDir, "lint-readability.sh");
+    await writeFile(outsideAbs, "#!/usr/bin/env bash\nset -euo pipefail\necho 'not-used'\n", "utf8");
+    await symlink(outsideAbs, join(rootDir, "scripts", "lint-readability.sh"));
+    const profile = parsePlatformProfile(makeProfileRaw({ readability: makeReadabilityPolicy() }), "platform-profile.json");
+    const chapterAbsPath = join(rootDir, "chapter.md");
+    await writeFile(chapterAbsPath, "# T\n正文\n", "utf8");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath,
+        chapterText: "# T\n正文\n",
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "fallback");
+    assert.ok(typeof report.script_error === "string" && report.script_error.includes("Unsafe path outside project root"));
+});
+test("computeReadabilityReport falls back when deterministic script output is invalid JSON", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-bad-json-test-"));
+    await mkdir(join(rootDir, "scripts"), { recursive: true });
+    const profile = parsePlatformProfile(makeProfileRaw({ readability: makeReadabilityPolicy() }), "platform-profile.json");
+    await writeFile(join(rootDir, "platform-profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    const chapterAbsPath = join(rootDir, "chapter.md");
+    await writeFile(chapterAbsPath, "# T\n正文\n", "utf8");
+    await writeFile(join(rootDir, "scripts", "lint-readability.sh"), "#!/usr/bin/env bash\nset -euo pipefail\necho 'not-json'\n", "utf8");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath,
+        chapterText: "# T\n正文\n",
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "fallback");
+    assert.ok(typeof report.script_error === "string" && report.script_error.includes("scripts/lint-readability.sh"));
+    assert.equal(report.has_blocking_issues, false);
+});
+test("computeReadabilityReport falls back when deterministic script returns wrong scope.chapter", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-wrong-chapter-test-"));
+    await mkdir(join(rootDir, "scripts"), { recursive: true });
+    const profile = parsePlatformProfile(makeProfileRaw({ readability: makeReadabilityPolicy() }), "platform-profile.json");
+    await writeFile(join(rootDir, "platform-profile.json"), `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    const chapterAbsPath = join(rootDir, "chapter.md");
+    await writeFile(chapterAbsPath, "# T\n正文\n", "utf8");
+    const wrongScopeJson = '{"schema_version":1,"generated_at":"2026-01-01T00:00:00.000Z","scope":{"chapter":2},"policy":{"enabled":true,"max_paragraph_chars":10,"max_consecutive_exposition_paragraphs":2,"blocking_severity":"hard_only"},"issues":[]}';
+    await writeFile(join(rootDir, "scripts", "lint-readability.sh"), `#!/usr/bin/env bash\nset -euo pipefail\nprintf '%s\\n' '${wrongScopeJson}'\n`, "utf8");
+    const report = await computeReadabilityReport({
+        rootDir,
+        chapter: 1,
+        chapterAbsPath,
+        chapterText: "# T\n正文\n",
+        platformProfile: profile
+    });
+    assert.equal(report.mode, "fallback");
+    assert.ok(typeof report.script_error === "string" && report.script_error.includes("scope.chapter=2"));
+    assert.equal(report.has_blocking_issues, false);
+});
+test("writeReadabilityLogs writes history under readability-report-chapter-*.json", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-readability-logs-test-"));
+    const report = {
+        schema_version: 1,
+        generated_at: "2026-01-01T00:00:00.000Z",
+        scope: { chapter: 1 },
+        policy: null,
+        mode: "fallback",
+        status: "pass",
+        issues: [],
+        has_blocking_issues: false
+    };
+    const out = await writeReadabilityLogs({ rootDir, chapter: 1, report });
+    assert.equal(out.latestRel, "logs/readability/latest.json");
+    assert.equal(out.historyRel, "logs/readability/readability-report-chapter-001.json");
+});

package/dist/__tests__/text-utils.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { truncateWithEllipsis } from "../text-utils.js";
+test("truncateWithEllipsis returns original when within limit", () => {
+    assert.equal(truncateWithEllipsis("abc", 3), "abc");
+    assert.equal(truncateWithEllipsis("abc", 10), "abc");
+});
+test("truncateWithEllipsis returns empty string for maxLen 0", () => {
+    assert.equal(truncateWithEllipsis("abc", 0), "");
+});
+test("truncateWithEllipsis returns ellipsis only for maxLen 1", () => {
+    assert.equal(truncateWithEllipsis("abc", 1), "\u2026");
+});
+test("truncateWithEllipsis truncates and appends ellipsis", () => {
+    assert.equal(truncateWithEllipsis("abcdef", 4), "abc\u2026");
+});
+test("truncateWithEllipsis does not split surrogate pairs", () => {
+    // "\uD83D\uDE00" is U+1F600 encoded as surrogate pair \uD83D\uDE00
+    const text = "ab\uD83D\uDE00cd";
+    // maxLen=4: would cut at index 3 which is inside the surrogate pair
+    const result = truncateWithEllipsis(text, 4);
+    // Should back up to avoid splitting: "ab" + "\u2026"
+    assert.equal(result, "ab\u2026");
+    // Verify no lone surrogate in output
+    for (let i = 0; i < result.length; i++) {
+        const code = result.charCodeAt(i);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = result.charCodeAt(i + 1);
+            assert.ok(next >= 0xdc00 && next <= 0xdfff, "high surrogate must be followed by low surrogate");
+        }
+    }
+});
+test("truncateWithEllipsis handles empty string", () => {
+    assert.equal(truncateWithEllipsis("", 5), "");
+});
+test("truncateWithEllipsis handles string exactly at limit boundary", () => {
+    assert.equal(truncateWithEllipsis("abcd", 4), "abcd");
+    assert.equal(truncateWithEllipsis("abcde", 4), "abc\u2026");
+});

package/dist/__tests__/title-policy.test.js

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parsePlatformProfile } from "../platform-profile.js";
+import { assertTitleFixOnlyChangedTitleLine, computeTitlePolicyReport, extractChapterTitleFromMarkdown, stripFirstAtxHeadingLine } from "../title-policy.js";
+function makeProfileRaw(extra) {
+    return {
+        schema_version: 1,
+        platform: "qidian",
+        created_at: "2026-01-01T00:00:00Z",
+        word_count: { target_min: 1, target_max: 2, hard_min: 1, hard_max: 2 },
+        hook_policy: { required: false, min_strength: 3, allowed_types: ["question"], fix_strategy: "hook-fix" },
+        info_load: { max_new_entities_per_chapter: 0, max_unknown_entities_per_chapter: 0, max_new_terms_per_1k_words: 0 },
+        compliance: { banned_words: ["禁词"], duplicate_name_policy: "warn" },
+        scoring: { genre_drive_type: "plot", weight_profile_id: "plot:v1" },
+        ...extra
+    };
+}
+function makeTitlePolicy(overrides = {}) {
+    return {
+        enabled: true,
+        min_chars: 2,
+        max_chars: 10,
+        forbidden_patterns: ["剧透"],
+        required_patterns: ["^第\\d+章"],
+        auto_fix: true,
+        ...overrides
+    };
+}
+function makeRetention(overrides = {}) {
+    return {
+        title_policy: makeTitlePolicy(),
+        hook_ledger: {
+            enabled: false,
+            fulfillment_window_chapters: 10,
+            diversity_window_chapters: 5,
+            max_same_type_streak: 2,
+            min_distinct_types_in_window: 2,
+            overdue_policy: "warn"
+        },
+        ...overrides
+    };
+}
+test("extractChapterTitleFromMarkdown returns the first non-empty H1 title", () => {
+    const out = extractChapterTitleFromMarkdown("\n\n# 第1章 开场\n正文");
+    assert.equal(out.has_h1, true);
+    assert.equal(out.title_text, "第1章 开场");
+    assert.equal(out.line_no, 3);
+});
+test("extractChapterTitleFromMarkdown reports missing H1 when first non-empty line is not H1", () => {
+    const out = extractChapterTitleFromMarkdown("正文\n# 标题");
+    assert.equal(out.has_h1, false);
+    assert.equal(out.line_no, 1);
+    assert.equal(out.raw_line, "正文");
+});
+test("computeTitlePolicyReport skips when title_policy is missing/disabled", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: null }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 标题\n正文", platformProfile: profile });
+    assert.equal(report.status, "skipped");
+});
+test("computeTitlePolicyReport detects missing H1 title as hard violation when enabled", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention() }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "正文", platformProfile: profile });
+    assert.equal(report.status, "violation");
+    assert.equal(report.has_hard_violations, true);
+    assert.ok(report.issues.some((i) => i.id.includes("missing_h1")));
+});
+test("computeTitlePolicyReport returns pass when title complies", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention({ title_policy: makeTitlePolicy({ forbidden_patterns: [], required_patterns: [] }) }) }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 合规标题\n正文", platformProfile: profile });
+    assert.equal(report.status, "pass");
+    assert.equal(report.issues.length, 0);
+});
+test("computeTitlePolicyReport flags empty title as hard violation", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention({ title_policy: makeTitlePolicy({ forbidden_patterns: [], required_patterns: [] }) }) }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "#   \n正文", platformProfile: profile });
+    assert.equal(report.status, "violation");
+    assert.equal(report.has_hard_violations, true);
+    assert.ok(report.issues.some((i) => i.id.includes("empty_title")));
+});
+test("computeTitlePolicyReport flags too-short title as warn (soft)", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({
+        retention: makeRetention({ title_policy: makeTitlePolicy({ min_chars: 5, forbidden_patterns: [], required_patterns: [] }) })
+    }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 短\n正文", platformProfile: profile });
+    assert.equal(report.status, "warn");
+    assert.equal(report.has_hard_violations, false);
+    assert.ok(report.issues.some((i) => i.id.includes("too_short")));
+});
+test("computeTitlePolicyReport flags too-long title as warn (soft)", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention({ title_policy: makeTitlePolicy({ max_chars: 3, required_patterns: [] }) }) }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 太长的标题\n正文", platformProfile: profile });
+    assert.equal(report.status, "warn");
+    assert.equal(report.has_hard_violations, false);
+    assert.ok(report.issues.some((i) => i.id.includes("too_long")));
+});
+test("computeTitlePolicyReport flags required-pattern mismatch as warn (soft)", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention() }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 开场\n正文", platformProfile: profile });
+    assert.equal(report.status, "warn");
+    assert.ok(report.issues.some((i) => i.id.includes("required_pattern_missing")));
+});
+test("computeTitlePolicyReport flags forbidden pattern matches as warn (soft)", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention({ title_policy: makeTitlePolicy({ required_patterns: [] }) }) }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 这是剧透\n正文", platformProfile: profile });
+    assert.equal(report.status, "warn");
+    assert.ok(report.issues.some((i) => i.id.includes("forbidden_pattern")));
+});
+test("computeTitlePolicyReport flags banned words in title as hard violation", () => {
+    const profile = parsePlatformProfile(makeProfileRaw({ retention: makeRetention({ title_policy: makeTitlePolicy({ forbidden_patterns: [], required_patterns: [] }) }) }), "platform-profile.json");
+    const report = computeTitlePolicyReport({ chapter: 1, chapterText: "# 禁词来了\n正文", platformProfile: profile });
+    assert.equal(report.status, "violation");
+    assert.equal(report.has_hard_violations, true);
+    assert.ok(report.issues.some((i) => i.id.includes("banned_words")));
+});
+test("stripFirstAtxHeadingLine strips the first ATX heading line (keeps bytes elsewhere)", () => {
+    const before = "\n## 旧标题\r\n正文\n";
+    const out = stripFirstAtxHeadingLine(before);
+    assert.equal(out.removed_line, "## 旧标题");
+    assert.equal(out.stripped, "\n正文\n");
+});
+test("stripFirstAtxHeadingLine returns unchanged when first non-empty line is not a heading", () => {
+    const before = "\n正文\n# 标题\n";
+    const out = stripFirstAtxHeadingLine(before);
+    assert.equal(out.removed_line, null);
+    assert.equal(out.stripped, before);
+});
+test("stripFirstAtxHeadingLine handles heading-only files without trailing newline", () => {
+    const before = "# 标题";
+    const out = stripFirstAtxHeadingLine(before);
+    assert.equal(out.removed_line, "# 标题");
+    assert.equal(out.stripped, "");
+});
+test("assertTitleFixOnlyChangedTitleLine allows inserting a new title line", () => {
+    const before = "\n正文第一段\n第二段\n";
+    const after = "\n# 新标题\n正文第一段\n第二段\n";
+    assert.doesNotThrow(() => assertTitleFixOnlyChangedTitleLine({ before, after, file: "chapters/chapter-001.md" }));
+});
+test("assertTitleFixOnlyChangedTitleLine allows promoting an existing ATX heading to H1", () => {
+    const before = "## 旧标题\n正文\n";
+    const after = "# 旧标题\n正文\n";
+    assert.doesNotThrow(() => assertTitleFixOnlyChangedTitleLine({ before, after, file: "chapters/chapter-001.md" }));
+});
+test("assertTitleFixOnlyChangedTitleLine rejects body changes", () => {
+    const before = "# 标题\n正文\n";
+    const after = "# 新标题\n正文改了\n";
+    assert.throws(() => assertTitleFixOnlyChangedTitleLine({ before, after, file: "chapters/chapter-001.md" }), /only change.*title line/i);
+});

package/dist/advance.js

@@ -0,0 +1,75 @@
+import { join } from "node:path";
+import { readCheckpoint, writeCheckpoint } from "./checkpoint.js";
+import { NovelCliError } from "./errors.js";
+import { removePath } from "./fs-utils.js";
+import { withWriteLock } from "./lock.js";
+import { chapterRelPaths, titleFixSnapshotRel } from "./steps.js";
+import { validateStep } from "./validate.js";
+function stageForStep(step) {
+    if (step.kind !== "chapter")
+        throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
+    switch (step.stage) {
+        case "draft":
+            return "drafting";
+        case "summarize":
+            return "drafted";
+        case "refine":
+            return "refined";
+        case "judge":
+            return "judged";
+        case "title-fix":
+            return "refined";
+        case "hook-fix":
+            return "refined";
+        default:
+            throw new NovelCliError(`Unsupported step stage: ${step.stage}`, 2);
+    }
+}
+export async function advanceCheckpointForStep(args) {
+    if (args.step.kind !== "chapter")
+        throw new NovelCliError(`Unsupported step kind: ${args.step.kind}`, 2);
+    if (args.step.stage === "commit")
+        throw new NovelCliError(`Use 'novel commit' for commit.`, 2);
+    if (args.step.stage === "review")
+        throw new NovelCliError(`Review is a manual step; do not advance it.`, 2);
+    return await withWriteLock(args.rootDir, { chapter: args.step.chapter }, async () => {
+        const checkpoint = await readCheckpoint(args.rootDir);
+        // Enforce validate-before-advance to keep deterministic semantics.
+        await validateStep({ rootDir: args.rootDir, checkpoint, step: args.step });
+        const updated = { ...checkpoint };
+        const nextStage = stageForStep(args.step);
+        updated.pipeline_stage = nextStage;
+        updated.inflight_chapter = args.step.chapter;
+        // Ensure revision counter is initialized when starting from draft (revision loops may preserve it).
+        if (args.step.stage === "draft") {
+            if (typeof updated.revision_count !== "number")
+                updated.revision_count = 0;
+            updated.hook_fix_count = 0;
+            updated.title_fix_count = 0;
+            await removePath(join(args.rootDir, titleFixSnapshotRel(args.step.chapter)));
+        }
+        // Title-fix counts as a bounded micro-revision and invalidates the current eval.
+        if (args.step.stage === "title-fix") {
+            const prev = typeof updated.title_fix_count === "number" ? updated.title_fix_count : 0;
+            if (prev >= 1) {
+                throw new NovelCliError(`Title-fix already attempted for chapter ${args.step.chapter}; manual review required.`, 2);
+            }
+            updated.title_fix_count = prev + 1;
+            const rel = chapterRelPaths(args.step.chapter);
+            await removePath(join(args.rootDir, rel.staging.evalJson));
+        }
+        // Hook-fix counts as a bounded micro-revision and invalidates the current eval.
+        if (args.step.stage === "hook-fix") {
+            const prev = typeof updated.hook_fix_count === "number" ? updated.hook_fix_count : 0;
+            if (prev >= 1) {
+                throw new NovelCliError(`Hook-fix already attempted for chapter ${args.step.chapter}; manual review required.`, 2);
+            }
+            updated.hook_fix_count = prev + 1;
+            const rel = chapterRelPaths(args.step.chapter);
+            await removePath(join(args.rootDir, rel.staging.evalJson));
+        }
+        updated.last_checkpoint_time = new Date().toISOString();
+        await writeCheckpoint(args.rootDir, updated);
+        return updated;
+    });
+}