novel-writer-cli 0.0.1

package/dist/scoring-weights.js

@@ -0,0 +1,290 @@
+import { join } from "node:path";
+import { NovelCliError } from "./errors.js";
+import { pathExists, readJsonFile, writeJsonFile } from "./fs-utils.js";
+import { isPlainObject } from "./type-guards.js";
+const CORE_DIMENSIONS = [
+    "plot_logic",
+    "character",
+    "immersion",
+    "foreshadowing",
+    "pacing",
+    "style_naturalness",
+    "emotional_impact",
+    "storyline_coherence",
+];
+const OPTIONAL_DIMENSIONS = ["hook_strength"];
+const KNOWN_DIMENSIONS = new Set([...CORE_DIMENSIONS, ...OPTIONAL_DIMENSIONS]);
+function requireIntField(obj, field, file) {
+    const v = obj[field];
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw new NovelCliError(`Invalid ${file}: '${field}' must be an int.`, 2);
+    return v;
+}
+function requireStringField(obj, field, file) {
+    const v = obj[field];
+    if (typeof v !== "string" || v.trim().length === 0)
+        throw new NovelCliError(`Invalid ${file}: '${field}' must be a non-empty string.`, 2);
+    return v.trim();
+}
+function requireFiniteNonNegativeNumber(value, file, field) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new NovelCliError(`Invalid ${file}: '${field}' must be a finite number >= 0.`, 2);
+    }
+    return value;
+}
+function requireStringArrayField(obj, field, file) {
+    const v = obj[field];
+    if (!Array.isArray(v) || !v.every((s) => typeof s === "string" && s.trim().length > 0)) {
+        throw new NovelCliError(`Invalid ${file}: '${field}' must be a non-empty string array.`, 2);
+    }
+    const uniq = Array.from(new Set(v.map((s) => s.trim()))).filter((s) => s.length > 0);
+    if (uniq.length === 0)
+        throw new NovelCliError(`Invalid ${file}: '${field}' must be a non-empty string array.`, 2);
+    return uniq;
+}
+function parseNormalizationSpec(raw, file) {
+    if (!isPlainObject(raw))
+        throw new NovelCliError(`Invalid ${file}: 'normalization' must be an object.`, 2);
+    const obj = raw;
+    const method = requireStringField(obj, "method", file);
+    if (method !== "scale_to_sum") {
+        throw new NovelCliError(`Invalid ${file}: 'normalization.method' must be 'scale_to_sum'.`, 2);
+    }
+    const sum_to = requireFiniteNonNegativeNumber(obj.sum_to, file, "normalization.sum_to");
+    if (sum_to <= 0)
+        throw new NovelCliError(`Invalid ${file}: 'normalization.sum_to' must be > 0.`, 2);
+    const tolerance = requireFiniteNonNegativeNumber(obj.tolerance, file, "normalization.tolerance");
+    return { method: "scale_to_sum", sum_to, tolerance };
+}
+export function parseGenreWeightProfiles(raw, file) {
+    if (!isPlainObject(raw))
+        throw new NovelCliError(`Invalid ${file}: expected a JSON object.`, 2);
+    const obj = raw;
+    const schema_version = requireIntField(obj, "schema_version", file);
+    if (schema_version !== 1)
+        throw new NovelCliError(`Invalid ${file}: 'schema_version' must be 1.`, 2);
+    const dimensions = requireStringArrayField(obj, "dimensions", file);
+    for (const dim of dimensions) {
+        if (!KNOWN_DIMENSIONS.has(dim)) {
+            throw new NovelCliError(`Invalid ${file}: unknown dimension '${dim}' in dimensions (allowed: ${Array.from(KNOWN_DIMENSIONS).join(", ")}).`, 2);
+        }
+    }
+    for (const required of CORE_DIMENSIONS) {
+        if (!dimensions.includes(required)) {
+            throw new NovelCliError(`Invalid ${file}: dimensions missing required core dimension '${required}'.`, 2);
+        }
+    }
+    const normalization = parseNormalizationSpec(obj.normalization, file);
+    if (!isPlainObject(obj.default_profile_by_drive_type)) {
+        throw new NovelCliError(`Invalid ${file}: 'default_profile_by_drive_type' must be an object.`, 2);
+    }
+    const dp = obj.default_profile_by_drive_type;
+    const default_profile_by_drive_type = {};
+    for (const [k, v] of Object.entries(dp)) {
+        if (typeof v !== "string" || v.trim().length === 0) {
+            throw new NovelCliError(`Invalid ${file}: 'default_profile_by_drive_type.${k}' must be a non-empty string.`, 2);
+        }
+        default_profile_by_drive_type[k.trim()] = v.trim();
+    }
+    if (!isPlainObject(obj.profiles))
+        throw new NovelCliError(`Invalid ${file}: 'profiles' must be an object.`, 2);
+    const profilesRaw = obj.profiles;
+    const profiles = {};
+    const allowedDims = new Set(dimensions);
+    for (const [profileId, profileRaw] of Object.entries(profilesRaw)) {
+        if (!isPlainObject(profileRaw))
+            throw new NovelCliError(`Invalid ${file}: 'profiles.${profileId}' must be an object.`, 2);
+        const p = profileRaw;
+        const drive_type = requireStringField(p, "drive_type", file);
+        if (!isPlainObject(p.weights))
+            throw new NovelCliError(`Invalid ${file}: 'profiles.${profileId}.weights' must be an object.`, 2);
+        const weightsRaw = p.weights;
+        const weights = {};
+        for (const [dim, val] of Object.entries(weightsRaw)) {
+            if (!allowedDims.has(dim)) {
+                throw new NovelCliError(`Invalid ${file}: unknown dimension '${dim}' in profiles.${profileId}.weights (allowed: ${dimensions.join(", ")}).`, 2);
+            }
+            weights[dim] = requireFiniteNonNegativeNumber(val, file, `profiles.${profileId}.weights.${dim}`);
+        }
+        for (const dim of dimensions) {
+            if (!(dim in weights)) {
+                throw new NovelCliError(`Invalid ${file}: profiles.${profileId}.weights missing required dimension '${dim}'.`, 2);
+            }
+        }
+        profiles[profileId] = { drive_type, weights };
+    }
+    // Validate default profile references.
+    for (const [driveType, profileId] of Object.entries(default_profile_by_drive_type)) {
+        const p = profiles[profileId];
+        if (!p)
+            throw new NovelCliError(`Invalid ${file}: default_profile_by_drive_type.${driveType} references missing profile '${profileId}'.`, 2);
+        if (p.drive_type !== driveType) {
+            throw new NovelCliError(`Invalid ${file}: default_profile_by_drive_type.${driveType} references profile '${profileId}' with drive_type='${p.drive_type}'.`, 2);
+        }
+    }
+    const out = {
+        schema_version: 1,
+        dimensions,
+        normalization,
+        default_profile_by_drive_type,
+        profiles
+    };
+    if (typeof obj.description === "string" && obj.description.trim().length > 0)
+        out.description = obj.description.trim();
+    if (typeof obj.last_updated === "string" && obj.last_updated.trim().length > 0)
+        out.last_updated = obj.last_updated.trim();
+    // Validate normalizability for each profile.
+    for (const [profileId, p] of Object.entries(profiles)) {
+        const sum = dimensions.reduce((acc, dim) => acc + p.weights[dim], 0);
+        if (!Number.isFinite(sum) || sum <= 0) {
+            throw new NovelCliError(`Invalid ${file}: profiles.${profileId} weights must have sum > 0 (got ${String(sum)}).`, 2);
+        }
+        const scale = normalization.sum_to / sum;
+        const sumAfter = dimensions.reduce((acc, dim) => acc + p.weights[dim] * scale, 0);
+        if (Math.abs(sumAfter - normalization.sum_to) > normalization.tolerance) {
+            throw new NovelCliError(`Invalid ${file}: profiles.${profileId} weights are not normalizable within tolerance (sum_after=${sumAfter}, expected ${normalization.sum_to}±${normalization.tolerance}).`, 2);
+        }
+    }
+    return out;
+}
+export async function loadGenreWeightProfiles(rootDir) {
+    const relPath = "genre-weight-profiles.json";
+    const absPath = join(rootDir, relPath);
+    if (!(await pathExists(absPath)))
+        return null;
+    const raw = await readJsonFile(absPath);
+    return { relPath, config: parseGenreWeightProfiles(raw, relPath) };
+}
+function normalizeWeights(args) {
+    const sum_before = args.dimensions.reduce((acc, dim) => acc + (args.weights[dim] ?? 0), 0);
+    if (!Number.isFinite(sum_before) || sum_before <= 0) {
+        throw new NovelCliError(`Invalid scoring weights (${args.fileHint}): weights must have sum > 0 (got ${String(sum_before)}).`, 2);
+    }
+    const scale_factor = args.normalization.sum_to / sum_before;
+    const sum_after = args.dimensions.reduce((acc, dim) => acc + (args.weights[dim] ?? 0) * scale_factor, 0);
+    if (Math.abs(sum_after - args.normalization.sum_to) > args.normalization.tolerance) {
+        throw new NovelCliError(`Invalid scoring weights (${args.fileHint}): weights are not normalizable within tolerance (sum_after=${sum_after}, expected ${args.normalization.sum_to}±${args.normalization.tolerance}).`, 2);
+    }
+    return { ...args.normalization, sum_before, scale_factor, sum_after };
+}
+export function computeEffectiveScoringWeights(args) {
+    const driveType = args.scoring.genre_drive_type;
+    const selectedProfileId = args.scoring.weight_profile_id;
+    const profile = args.config.profiles[selectedProfileId];
+    if (!profile) {
+        const known = Object.keys(args.config.profiles).sort();
+        const hint = known.length > 0 ? ` Known profiles: ${known.join(", ")}` : "";
+        throw new NovelCliError(`Invalid platform-profile.json: scoring.weight_profile_id='${selectedProfileId}' not found in genre-weight-profiles.json.${hint}`, 2);
+    }
+    if (profile.drive_type !== driveType) {
+        throw new NovelCliError(`Invalid platform-profile.json: scoring.genre_drive_type='${driveType}' does not match selected profile '${selectedProfileId}' (drive_type='${profile.drive_type}').`, 2);
+    }
+    // When hook policy is enabled, hook_strength should be a first-class dimension.
+    const configDims = args.config.dimensions;
+    if (args.hookPolicy?.required && !configDims.includes("hook_strength")) {
+        throw new NovelCliError(`Invalid genre-weight-profiles.json: missing 'hook_strength' in dimensions while platform-profile.json.hook_policy.required=true.`, 2);
+    }
+    // Effective dimensions: hook_strength only participates when hooks are enabled.
+    const dims = args.hookPolicy?.required ? configDims : configDims.filter((d) => d !== "hook_strength");
+    const overridesRaw = args.scoring.weight_overrides ?? null;
+    const overrides = overridesRaw ? { ...overridesRaw } : null;
+    const allowedDims = new Set(configDims);
+    const effectiveDims = new Set(dims);
+    if (overrides) {
+        for (const [dim, v] of Object.entries(overrides)) {
+            if (!allowedDims.has(dim)) {
+                throw new NovelCliError(`Invalid platform-profile.json: scoring.weight_overrides has unknown dimension '${dim}' (allowed: ${configDims.join(", ")}).`, 2);
+            }
+            overrides[dim] = requireFiniteNonNegativeNumber(v, "platform-profile.json", `scoring.weight_overrides.${dim}`);
+            if (dim === "hook_strength" && !args.hookPolicy?.required && overrides[dim] > 0) {
+                throw new NovelCliError(`Invalid platform-profile.json: scoring.weight_overrides.hook_strength=${overrides[dim]} but hook_policy.required=false. Set hook_strength override to 0 or enable hook_policy.required.`, 2);
+            }
+            if (!effectiveDims.has(dim)) {
+                // Currently only possible for hook_strength when hook policy is disabled. Allowed as long as it is not positive.
+                continue;
+            }
+        }
+    }
+    const rawWeights = {};
+    for (const dim of dims) {
+        rawWeights[dim] = typeof overrides?.[dim] === "number" ? overrides[dim] : profile.weights[dim];
+    }
+    const normalization = normalizeWeights({
+        dimensions: dims,
+        normalization: args.config.normalization,
+        weights: rawWeights,
+        fileHint: "platform-profile.json.scoring + genre-weight-profiles.json"
+    });
+    const weights = {};
+    for (const dim of dims) {
+        weights[dim] = rawWeights[dim] * normalization.scale_factor;
+    }
+    return {
+        genre_drive_type: driveType,
+        weight_profile_id: selectedProfileId,
+        weight_overrides: overrides,
+        dimensions: dims,
+        weights,
+        normalization
+    };
+}
+function getScoresTargets(evalObj) {
+    const targets = [];
+    const evalUsed = evalObj.eval_used;
+    if (isPlainObject(evalUsed) && isPlainObject(evalUsed.scores)) {
+        targets.push({ scores: evalUsed.scores, path: "eval_used.scores" });
+    }
+    const topScores = evalObj.scores;
+    if (isPlainObject(topScores)) {
+        targets.push({ scores: topScores, path: "scores" });
+    }
+    return targets;
+}
+export async function attachScoringWeightsToEval(args) {
+    const scoring = args.platformProfile.scoring;
+    if (!scoring)
+        return;
+    const effective = computeEffectiveScoringWeights({
+        config: args.genreWeightProfiles.config,
+        scoring,
+        hookPolicy: args.platformProfile.hook_policy
+    });
+    const raw = await readJsonFile(args.evalAbsPath);
+    if (!isPlainObject(raw))
+        throw new NovelCliError(`Invalid ${args.evalRelPath}: eval JSON must be an object.`, 2);
+    const obj = raw;
+    obj.scoring_weights = {
+        genre_drive_type: effective.genre_drive_type,
+        weight_profile_id: effective.weight_profile_id,
+        weight_overrides: effective.weight_overrides,
+        dimensions: effective.dimensions,
+        weights: effective.weights,
+        normalization: effective.normalization,
+        source: {
+            platform_profile: "platform-profile.json",
+            genre_weight_profiles: args.genreWeightProfiles.relPath
+        }
+    };
+    const targets = getScoresTargets(obj);
+    if (targets.length === 0) {
+        throw new NovelCliError(`Invalid ${args.evalRelPath}: missing scores object (expected 'scores' or 'eval_used.scores'); cannot attach per-dimension weights.`, 2);
+    }
+    const canonical = targets[0];
+    const missing = [];
+    for (const dim of effective.dimensions) {
+        if (!isPlainObject(canonical.scores[dim]))
+            missing.push(dim);
+    }
+    if (missing.length > 0) {
+        throw new NovelCliError(`Invalid ${args.evalRelPath}: missing score dimensions in ${canonical.path}: ${missing.join(", ")}. Re-run QualityJudge with the updated contract.`, 2);
+    }
+    for (const target of targets) {
+        for (const dim of effective.dimensions) {
+            const entry = target.scores[dim];
+            if (!isPlainObject(entry))
+                continue;
+            entry.weight = effective.weights[dim] ?? 0;
+        }
+    }
+    await writeJsonFile(args.evalAbsPath, obj);
+}

package/dist/steps.js

@@ -0,0 +1,60 @@
+import { NovelCliError } from "./errors.js";
+export const CHAPTER_STAGES = ["draft", "summarize", "refine", "judge", "title-fix", "hook-fix", "review", "commit"];
+export function pad3(n) {
+    return String(n).padStart(3, "0");
+}
+export function pad2(n) {
+    return String(n).padStart(2, "0");
+}
+export function titleFixSnapshotRel(chapter) {
+    return `staging/logs/title-fix-chapter-${pad3(chapter)}-before.md`;
+}
+export function formatStepId(step) {
+    if (step.kind !== "chapter")
+        throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
+    return `chapter:${pad3(step.chapter)}:${step.stage}`;
+}
+export function parseStepId(input) {
+    const trimmed = input.trim();
+    const parts = trimmed.split(":");
+    if (parts.length !== 3) {
+        throw new NovelCliError(`Invalid step id: ${input}. Expected format: chapter:048:draft`, 2);
+    }
+    const [kind, chapterRaw, stageRaw] = parts;
+    if (kind !== "chapter")
+        throw new NovelCliError(`Invalid step id: ${input}. Only 'chapter' steps are supported.`, 2);
+    if (!/^\d+$/.test(chapterRaw))
+        throw new NovelCliError(`Invalid step id: ${input}. Chapter must be a number.`, 2);
+    const chapter = Number.parseInt(chapterRaw, 10);
+    if (!Number.isInteger(chapter) || chapter <= 0) {
+        throw new NovelCliError(`Invalid step id: ${input}. Chapter must be an int >= 1.`, 2);
+    }
+    if (!CHAPTER_STAGES.includes(stageRaw)) {
+        throw new NovelCliError(`Invalid step id: ${input}. Stage must be one of: ${CHAPTER_STAGES.join(", ")}`, 2);
+    }
+    return { kind: "chapter", chapter, stage: stageRaw };
+}
+export function chapterRelPaths(chapter, storylineId) {
+    const id = pad3(chapter);
+    return {
+        staging: {
+            chapterMd: `staging/chapters/chapter-${id}.md`,
+            summaryMd: `staging/summaries/chapter-${id}-summary.md`,
+            deltaJson: `staging/state/chapter-${id}-delta.json`,
+            crossrefJson: `staging/state/chapter-${id}-crossref.json`,
+            evalJson: `staging/evaluations/chapter-${id}-eval.json`,
+            styleRefinerChangesJson: `staging/logs/style-refiner-chapter-${id}-changes.json`,
+            storylineMemoryMd: storylineId ? `staging/storylines/${storylineId}/memory.md` : null
+        },
+        final: {
+            chapterMd: `chapters/chapter-${id}.md`,
+            summaryMd: `summaries/chapter-${id}-summary.md`,
+            evalJson: `evaluations/chapter-${id}-eval.json`,
+            crossrefJson: `state/chapter-${id}-crossref.json`,
+            storylineMemoryMd: storylineId ? `storylines/${storylineId}/memory.md` : null,
+            foreshadowGlobalJson: "foreshadowing/global.json",
+            stateCurrentJson: "state/current-state.json",
+            stateChangelogJsonl: "state/changelog.jsonl"
+        }
+    };
+}

package/dist/text-utils.js

@@ -0,0 +1,18 @@
+export function truncateWithEllipsis(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    if (maxLen <= 0)
+        return "";
+    if (maxLen === 1)
+        return "…";
+    let end = Math.max(0, maxLen - 1);
+    if (end > 0) {
+        const last = text.charCodeAt(end - 1);
+        if (last >= 0xd800 && last <= 0xdbff) {
+            const next = text.charCodeAt(end);
+            if (next >= 0xdc00 && next <= 0xdfff)
+                end -= 1;
+        }
+    }
+    return `${text.slice(0, end)}…`;
+}

package/dist/title-policy.js

@@ -0,0 +1,251 @@
+import { join } from "node:path";
+import { NovelCliError } from "./errors.js";
+import { ensureDir, writeJsonFile } from "./fs-utils.js";
+import { pad3 } from "./steps.js";
+function countOccurrences(text, needle) {
+    if (!needle)
+        return 0;
+    let count = 0;
+    let idx = 0;
+    while (true) {
+        const next = text.indexOf(needle, idx);
+        if (next < 0)
+            break;
+        count += 1;
+        idx = next + needle.length;
+    }
+    return count;
+}
+function extractFirstNonEmptyLine(text) {
+    const lines = text.split(/\r?\n/gu);
+    for (const [i, line] of lines.entries()) {
+        if (line.trim().length === 0)
+            continue;
+        return { line, line_no: i + 1 };
+    }
+    return null;
+}
+export function extractChapterTitleFromMarkdown(text) {
+    const first = extractFirstNonEmptyLine(text);
+    if (!first)
+        return { has_h1: false, line_no: null, raw_line: null, title_text: null };
+    // CommonMark: up to 3 leading spaces allowed; allow optional BOM for robustness.
+    const m = /^(?:\uFEFF)? {0,3}#(?!#)\s*(.*)$/u.exec(first.line);
+    if (!m)
+        return { has_h1: false, line_no: first.line_no, raw_line: first.line, title_text: null };
+    const title_text = (m[1] ?? "").trim();
+    return { has_h1: true, line_no: first.line_no, raw_line: first.line, title_text: title_text.length > 0 ? title_text : null };
+}
+export function computeTitlePolicyReport(args) {
+    const generated_at = new Date().toISOString();
+    const titlePolicy = args.platformProfile.retention?.title_policy ?? null;
+    const policy = titlePolicy
+        ? {
+            enabled: titlePolicy.enabled,
+            min_chars: titlePolicy.min_chars,
+            max_chars: titlePolicy.max_chars,
+            forbidden_patterns: titlePolicy.forbidden_patterns,
+            ...(titlePolicy.required_patterns ? { required_patterns: titlePolicy.required_patterns } : {}),
+            auto_fix: titlePolicy.auto_fix
+        }
+        : null;
+    const extracted = extractChapterTitleFromMarkdown(args.chapterText);
+    const titleText = extracted.title_text;
+    const chars = titleText ? Array.from(titleText).length : null;
+    const issues = [];
+    if (!titlePolicy || !titlePolicy.enabled) {
+        return {
+            schema_version: 1,
+            generated_at,
+            scope: { chapter: args.chapter },
+            title: {
+                has_h1: extracted.has_h1,
+                line_no: extracted.line_no,
+                raw_line: extracted.raw_line,
+                text: titleText,
+                chars
+            },
+            policy,
+            status: "skipped",
+            issues: [],
+            has_hard_violations: false
+        };
+    }
+    if (!extracted.has_h1) {
+        issues.push({
+            id: "retention.title_policy.missing_h1",
+            severity: "hard",
+            summary: "Missing chapter title: expected the first non-empty line to be a Markdown H1 ('# ...').",
+            evidence: extracted.raw_line ?? undefined,
+            suggestion: "Add an H1 title as the first non-empty line, and keep it within configured length/pattern rules."
+        });
+    }
+    else if (!titleText) {
+        issues.push({
+            id: "retention.title_policy.empty_title",
+            severity: "hard",
+            summary: "Empty chapter title: H1 line exists but title text is missing.",
+            evidence: extracted.raw_line ?? undefined,
+            suggestion: "Fill in a meaningful title (avoid spoilers) and keep it within configured length/pattern rules."
+        });
+    }
+    if (titleText && chars !== null) {
+        if (chars < titlePolicy.min_chars) {
+            issues.push({
+                id: "retention.title_policy.too_short",
+                severity: "soft",
+                summary: `Title is too short (${chars} chars < min ${titlePolicy.min_chars}).`,
+                evidence: titleText,
+                suggestion: "Expand the title to better signal the chapter's hook without spoilers."
+            });
+        }
+        if (chars > titlePolicy.max_chars) {
+            issues.push({
+                id: "retention.title_policy.too_long",
+                severity: "soft",
+                summary: `Title is too long (${chars} chars > max ${titlePolicy.max_chars}).`,
+                evidence: titleText,
+                suggestion: "Shorten the title; keep the promise clear and avoid padding words."
+            });
+        }
+        // Banned words: reuse platform-profile compliance list.
+        const bannedHits = [];
+        for (const word of args.platformProfile.compliance.banned_words) {
+            const count = countOccurrences(titleText, word);
+            if (count <= 0)
+                continue;
+            bannedHits.push({ word, count });
+        }
+        if (bannedHits.length > 0) {
+            bannedHits.sort((a, b) => b.count - a.count || a.word.localeCompare(b.word, "zh"));
+            const top = bannedHits[0];
+            issues.push({
+                id: "retention.title_policy.banned_words",
+                severity: "hard",
+                summary: `Title contains banned words (${bannedHits.length} distinct).`,
+                evidence: top ? `${top.word} x${top.count}` : undefined,
+                suggestion: "Remove or replace banned words in the title."
+            });
+        }
+        // Forbidden patterns.
+        for (const [i, pattern] of titlePolicy.forbidden_patterns.entries()) {
+            let re;
+            try {
+                re = new RegExp(pattern);
+            }
+            catch {
+                issues.push({
+                    id: `retention.title_policy.invalid_forbidden_pattern.${i}`,
+                    severity: "soft",
+                    summary: `Invalid forbidden_patterns regex: /${pattern}/ — skipped.`,
+                    suggestion: "Fix the regex syntax in platform-profile.json."
+                });
+                continue;
+            }
+            const m = re.exec(titleText);
+            if (!m)
+                continue;
+            const match = (m[0] ?? "").trim();
+            issues.push({
+                id: `retention.title_policy.forbidden_pattern.${i}`,
+                severity: "soft",
+                summary: `Title matches forbidden pattern /${pattern}/.`,
+                evidence: match.length > 0 ? match : titleText,
+                suggestion: "Adjust the title to avoid forbidden patterns (spoilers/markers/phrases)."
+            });
+        }
+        // Required patterns (OR semantics).
+        if (titlePolicy.required_patterns && titlePolicy.required_patterns.length > 0) {
+            const ok = titlePolicy.required_patterns.some((p) => {
+                try {
+                    return new RegExp(p).test(titleText);
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (!ok) {
+                issues.push({
+                    id: "retention.title_policy.required_pattern_missing",
+                    severity: "soft",
+                    summary: "Title does not match any required pattern configured by the platform policy.",
+                    evidence: titleText,
+                    suggestion: "Rewrite the title to match one of the required patterns (e.g. '第XX章 …')."
+                });
+            }
+        }
+    }
+    const hasHard = issues.some((i) => i.severity === "hard");
+    const status = issues.length === 0 ? "pass" : hasHard ? "violation" : "warn";
+    return {
+        schema_version: 1,
+        generated_at,
+        scope: { chapter: args.chapter },
+        title: {
+            has_h1: extracted.has_h1,
+            line_no: extracted.line_no,
+            raw_line: extracted.raw_line,
+            text: titleText,
+            chars
+        },
+        policy,
+        status,
+        issues,
+        has_hard_violations: hasHard
+    };
+}
+export async function writeTitlePolicyLogs(args) {
+    const dirRel = "logs/retention/title-policy";
+    const dirAbs = join(args.rootDir, dirRel);
+    await ensureDir(dirAbs);
+    const historyRel = `${dirRel}/title-policy-chapter-${pad3(args.chapter)}.json`;
+    const latestRel = `${dirRel}/latest.json`;
+    await writeJsonFile(join(args.rootDir, historyRel), args.report);
+    await writeJsonFile(join(args.rootDir, latestRel), args.report);
+    return { latestRel, historyRel };
+}
+// Strip the first non-empty ATX heading line (H1–H6) from the original text.
+// This is used for the title-fix body guard: it intentionally treats `## ...` as a title-line candidate so title-fix can promote it to `# ...`.
+export function stripFirstAtxHeadingLine(text) {
+    let scanIdx = 0;
+    const findNextLine = () => {
+        if (scanIdx > text.length)
+            return null;
+        const nextNl = text.indexOf("\n", scanIdx);
+        if (nextNl === -1) {
+            const line = text.slice(scanIdx);
+            const start = scanIdx;
+            const end = text.length;
+            scanIdx = text.length + 1;
+            return { line, start, end };
+        }
+        const line = text.slice(scanIdx, nextNl).replace(/\r$/u, "");
+        const start = scanIdx;
+        const end = nextNl + 1;
+        scanIdx = end;
+        return { line, start, end };
+    };
+    // Find first non-empty line by scanning the original string to preserve exact slicing.
+    while (true) {
+        const next = findNextLine();
+        if (!next)
+            return { stripped: text, removed_line: null };
+        const trimmed = next.line.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        // Treat the first non-empty ATX heading (H1–H6, up to 3 leading spaces) as the title-line candidate.
+        if (!/^(?:\uFEFF)? {0,3}#{1,6}(?!#)\s*.*$/u.test(next.line)) {
+            return { stripped: text, removed_line: null };
+        }
+        const stripped = text.slice(0, next.start) + text.slice(next.end);
+        return { stripped, removed_line: next.line };
+    }
+}
+export function assertTitleFixOnlyChangedTitleLine(args) {
+    const b = stripFirstAtxHeadingLine(args.before);
+    const a = stripFirstAtxHeadingLine(args.after);
+    if (b.stripped !== a.stripped) {
+        throw new NovelCliError(`Invalid ${args.file}: title-fix must only change the first title line; chapter body changed.`, 2);
+    }
+}

package/dist/type-guards.js

@@ -0,0 +1,6 @@
+export function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}