novel-writer-cli 0.0.3 → 0.1.0

package/dist/validate.js

@@ -7,6 +7,8 @@ import { rejectPathTraversalInput } from "./safe-path.js";
 import { chapterRelPaths, formatStepId, titleFixSnapshotRel } from "./steps.js";
 import { assertTitleFixOnlyChangedTitleLine, extractChapterTitleFromMarkdown } from "./title-policy.js";
 import { isPlainObject } from "./type-guards.js";
+import { VOL_REVIEW_RELS } from "./volume-review.js";
+import { computeVolumeChapterRange, volumeFinalRelPaths, volumeForChapter, volumeStagingRelPaths } from "./volume-planning.js";
 function requireFile(exists, relPath) {
     if (!exists)
         throw new NovelCliError(`Missing required file: ${relPath}`, 2);
@@ -26,9 +28,280 @@ function requireNumberField(obj, field, file) {
 export async function validateStep(args) {
     const warnings = [];
     const stepId = formatStepId(args.step);
-    if (args.step.kind !== "chapter") {
-        throw new NovelCliError(`Unsupported step: ${stepId}`, 2);
+    if (args.step.kind === "review") {
+        const qualitySummaryAbs = join(args.rootDir, VOL_REVIEW_RELS.qualitySummary);
+        const auditReportAbs = join(args.rootDir, VOL_REVIEW_RELS.auditReport);
+        const reviewReportAbs = join(args.rootDir, VOL_REVIEW_RELS.reviewReport);
+        const foreshadowAbs = join(args.rootDir, VOL_REVIEW_RELS.foreshadowStatus);
+        if (args.step.phase === "collect") {
+            requireFile(await pathExists(qualitySummaryAbs), VOL_REVIEW_RELS.qualitySummary);
+            const raw = await readJsonFile(qualitySummaryAbs);
+            if (!isPlainObject(raw))
+                throw new NovelCliError(`Invalid ${VOL_REVIEW_RELS.qualitySummary}: expected JSON object.`, 2);
+            if (raw.schema_version !== 1)
+                warnings.push(`Unexpected schema_version in ${VOL_REVIEW_RELS.qualitySummary}.`);
+            return { ok: true, step: stepId, warnings };
+        }
+        if (args.step.phase === "audit") {
+            requireFile(await pathExists(qualitySummaryAbs), VOL_REVIEW_RELS.qualitySummary);
+            requireFile(await pathExists(auditReportAbs), VOL_REVIEW_RELS.auditReport);
+            const raw = await readJsonFile(auditReportAbs);
+            if (!isPlainObject(raw))
+                throw new NovelCliError(`Invalid ${VOL_REVIEW_RELS.auditReport}: expected JSON object.`, 2);
+            if (raw.schema_version !== 1)
+                warnings.push(`Unexpected schema_version in ${VOL_REVIEW_RELS.auditReport}.`);
+            return { ok: true, step: stepId, warnings };
+        }
+        if (args.step.phase === "report") {
+            requireFile(await pathExists(qualitySummaryAbs), VOL_REVIEW_RELS.qualitySummary);
+            requireFile(await pathExists(auditReportAbs), VOL_REVIEW_RELS.auditReport);
+            requireFile(await pathExists(reviewReportAbs), VOL_REVIEW_RELS.reviewReport);
+            const text = await readTextFile(reviewReportAbs);
+            if (text.trim().length === 0)
+                throw new NovelCliError(`Empty report file: ${VOL_REVIEW_RELS.reviewReport}`, 2);
+            return { ok: true, step: stepId, warnings };
+        }
+        if (args.step.phase === "cleanup") {
+            requireFile(await pathExists(foreshadowAbs), VOL_REVIEW_RELS.foreshadowStatus);
+            const raw = await readJsonFile(foreshadowAbs);
+            if (!isPlainObject(raw))
+                throw new NovelCliError(`Invalid ${VOL_REVIEW_RELS.foreshadowStatus}: expected JSON object.`, 2);
+            if (raw.schema_version !== 1)
+                warnings.push(`Unexpected schema_version in ${VOL_REVIEW_RELS.foreshadowStatus}.`);
+            return { ok: true, step: stepId, warnings };
+        }
+        if (args.step.phase === "transition") {
+            requireFile(await pathExists(qualitySummaryAbs), VOL_REVIEW_RELS.qualitySummary);
+            requireFile(await pathExists(auditReportAbs), VOL_REVIEW_RELS.auditReport);
+            requireFile(await pathExists(reviewReportAbs), VOL_REVIEW_RELS.reviewReport);
+            requireFile(await pathExists(foreshadowAbs), VOL_REVIEW_RELS.foreshadowStatus);
+            return { ok: true, step: stepId, warnings };
+        }
+        const _exhaustive = args.step.phase;
+        throw new NovelCliError(`Unsupported review phase: ${String(_exhaustive)}`, 2);
+    }
+    if (args.step.kind === "volume") {
+        const volume = args.checkpoint.current_volume;
+        const range = computeVolumeChapterRange({ current_volume: volume, last_completed_chapter: args.checkpoint.last_completed_chapter });
+        const rels = volumeStagingRelPaths(volume);
+        const requireVolumePlanArtifacts = async () => {
+            requireFile(await pathExists(join(args.rootDir, rels.outlineMd)), rels.outlineMd);
+            requireFile(await pathExists(join(args.rootDir, rels.storylineScheduleJson)), rels.storylineScheduleJson);
+            requireFile(await pathExists(join(args.rootDir, rels.foreshadowingJson)), rels.foreshadowingJson);
+            requireFile(await pathExists(join(args.rootDir, rels.newCharactersJson)), rels.newCharactersJson);
+            for (let ch = range.start; ch <= range.end; ch++) {
+                requireFile(await pathExists(join(args.rootDir, rels.chapterContractJson(ch))), rels.chapterContractJson(ch));
+            }
+        };
+        const outlineAbs = join(args.rootDir, rels.outlineMd);
+        const parseOutlineStorylineIds = async () => {
+            const text = await readTextFile(outlineAbs);
+            if (text.trim().length === 0)
+                throw new NovelCliError(`Empty outline file: ${rels.outlineMd}`, 2);
+            const lines = text.split(/\r?\n/u);
+            const chapters = [];
+            const chapterHeadingRe = /^###\s*第\s*(\d+)\s*章/u;
+            for (let i = 0; i < lines.length; i++) {
+                const m = chapterHeadingRe.exec(lines[i] ?? "");
+                if (!m)
+                    continue;
+                const chapter = Number.parseInt(m[1] ?? "", 10);
+                if (!Number.isInteger(chapter) || chapter < 1)
+                    continue;
+                chapters.push({ chapter, startLine: i, endLine: lines.length });
+            }
+            if (chapters.length === 0) {
+                throw new NovelCliError(`Invalid outline: could not parse any chapter headings. Expected lines like "### 第 1 章" (spaces are flexible). File: ${rels.outlineMd}`, 2);
+            }
+            for (let i = 0; i < chapters.length; i++) {
+                const cur = chapters[i];
+                const next = chapters[i + 1];
+                if (next)
+                    cur.endLine = next.startLine;
+            }
+            const seen = new Set();
+            for (const c of chapters) {
+                if (seen.has(c.chapter))
+                    throw new NovelCliError(`Invalid outline: duplicate chapter block for chapter ${c.chapter} (${rels.outlineMd}).`, 2);
+                seen.add(c.chapter);
+            }
+            for (let ch = range.start; ch <= range.end; ch++) {
+                if (!seen.has(ch)) {
+                    throw new NovelCliError(`Invalid outline: missing chapter block for chapter ${ch} (expected continuous coverage ${range.start}-${range.end}). File: ${rels.outlineMd}`, 2);
+                }
+            }
+            const requiredKeys = [
+                "Storyline",
+                "POV",
+                "Location",
+                "Conflict",
+                "Arc",
+                "Foreshadowing",
+                "StateChanges",
+                "TransitionHint"
+            ];
+            const storylinesByChapter = new Map();
+            for (const c of chapters) {
+                if (c.chapter < range.start || c.chapter > range.end)
+                    continue;
+                const blockLines = lines.slice(c.startLine, c.endLine);
+                const keyFound = new Set();
+                let storylineId = null;
+                for (const line of blockLines) {
+                    for (const k of requiredKeys) {
+                        const prefix = `- **${k}**:`;
+                        if (line.startsWith(prefix)) {
+                            keyFound.add(k);
+                            if (k === "Storyline") {
+                                const val = line.slice(prefix.length).trim();
+                                if (val.length > 0)
+                                    storylineId = val;
+                            }
+                        }
+                    }
+                }
+                for (const k of requiredKeys) {
+                    if (!keyFound.has(k)) {
+                        throw new NovelCliError(`Invalid outline: chapter ${c.chapter} block missing required key '${k}' line. File: ${rels.outlineMd}`, 2);
+                    }
+                }
+                if (!storylineId) {
+                    throw new NovelCliError(`Invalid outline: chapter ${c.chapter} missing non-empty Storyline value. File: ${rels.outlineMd}`, 2);
+                }
+                storylinesByChapter.set(c.chapter, storylineId);
+            }
+            return storylinesByChapter;
+        };
+        const validateNewCharacters = (raw) => {
+            if (!Array.isArray(raw))
+                throw new NovelCliError(`Invalid ${rels.newCharactersJson}: expected an array.`, 2);
+            for (const [idx, item] of raw.entries()) {
+                if (!isPlainObject(item))
+                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} must be an object.`, 2);
+                const obj = item;
+                const name = typeof obj.name === "string" ? obj.name.trim() : "";
+                const role = typeof obj.role === "string" ? obj.role.trim() : "";
+                const brief = typeof obj.brief === "string" ? obj.brief.trim() : "";
+                const firstChapter = typeof obj.first_chapter === "number" && Number.isInteger(obj.first_chapter) ? obj.first_chapter : null;
+                if (name.length === 0)
+                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} missing name.`, 2);
+                if (brief.length === 0)
+                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} missing brief.`, 2);
+                if (firstChapter === null || firstChapter < range.start || firstChapter > range.end) {
+                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} first_chapter=${String(obj.first_chapter)} out of range (${range.start}-${range.end}).`, 2);
+                }
+                if (role !== "antagonist" && role !== "supporting" && role !== "minor") {
+                    throw new NovelCliError(`Invalid ${rels.newCharactersJson}: entry ${idx} role must be one of: antagonist, supporting, minor.`, 2);
+                }
+            }
+        };
+        const validateSchedule = (raw, storylinesByChapter) => {
+            if (!isPlainObject(raw))
+                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: must be an object.`, 2);
+            const obj = raw;
+            const active = obj.active_storylines;
+            if (!Array.isArray(active))
+                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: missing active_storylines array.`, 2);
+            const activeIds = [];
+            for (const [idx, v] of active.entries()) {
+                if (typeof v !== "string") {
+                    warnings.push(`WARN ${rels.storylineScheduleJson}: active_storylines[${idx}] is not a string; ignoring.`);
+                    continue;
+                }
+                const id = v.trim();
+                if (id.length > 0)
+                    activeIds.push(id);
+            }
+            if (activeIds.length === 0)
+                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: active_storylines must be non-empty.`, 2);
+            if (activeIds.length > 4)
+                throw new NovelCliError(`Invalid ${rels.storylineScheduleJson}: active_storylines length must be <= 4.`, 2);
+            const activeSet = new Set(activeIds);
+            for (const [ch, storylineId] of storylinesByChapter.entries()) {
+                if (!activeSet.has(storylineId)) {
+                    throw new NovelCliError(`Invalid volume plan: outline chapter ${ch} Storyline=${storylineId} not in storyline-schedule.json.active_storylines.`, 2);
+                }
+            }
+        };
+        const validateForeshadowingPlan = (raw) => {
+            if (!isPlainObject(raw)) {
+                throw new NovelCliError(`Invalid ${rels.foreshadowingJson}: expected JSON object with {schema_version, items}.`, 2);
+            }
+            const obj = raw;
+            const schema = obj.schema_version;
+            if (schema !== 1)
+                warnings.push(`Unexpected schema_version in ${rels.foreshadowingJson}.`);
+            const items = obj.items;
+            if (!Array.isArray(items))
+                throw new NovelCliError(`Invalid ${rels.foreshadowingJson}: items must be an array.`, 2);
+        };
+        const validateContracts = async (storylinesByChapter) => {
+            for (let ch = range.start; ch <= range.end; ch++) {
+                const rel = rels.chapterContractJson(ch);
+                const raw = await readJsonFile(join(args.rootDir, rel));
+                if (!isPlainObject(raw))
+                    throw new NovelCliError(`Invalid ${rel}: must be an object.`, 2);
+                const obj = raw;
+                const chapter = requireNumberField(obj, "chapter", rel);
+                if (!Number.isInteger(chapter) || chapter !== ch)
+                    throw new NovelCliError(`Invalid ${rel}: chapter=${chapter} expected ${ch}.`, 2);
+                const storylineId = requireStringField(obj, "storyline_id", rel).trim();
+                const expectedStorylineId = storylinesByChapter.get(ch) ?? null;
+                if (!expectedStorylineId || storylineId !== expectedStorylineId) {
+                    throw new NovelCliError(`Invalid ${rel}: storyline_id=${storylineId} expected ${expectedStorylineId ?? "(missing in outline)"}.`, 2);
+                }
+                const objectivesRaw = obj.objectives;
+                if (!Array.isArray(objectivesRaw))
+                    throw new NovelCliError(`Invalid ${rel}: objectives must be an array.`, 2);
+                const hasRequired = objectivesRaw.some((it) => isPlainObject(it) && it.required === true);
+                if (!hasRequired)
+                    throw new NovelCliError(`Invalid ${rel}: objectives must include at least one entry with required=true.`, 2);
+                // Chain propagation (minimal): prev.postconditions.state_changes keys must exist in current.preconditions.character_states.
+                const prevChapter = ch - 1;
+                if (prevChapter >= 1) {
+                    const prevRel = prevChapter >= range.start
+                        ? rels.chapterContractJson(prevChapter)
+                        : volumeFinalRelPaths(volumeForChapter(prevChapter)).chapterContractJson(prevChapter);
+                    if (await pathExists(join(args.rootDir, prevRel))) {
+                        const prevRaw = await readJsonFile(join(args.rootDir, prevRel));
+                        if (isPlainObject(prevRaw)) {
+                            const prevObj = prevRaw;
+                            const post = isPlainObject(prevObj.postconditions) ? prevObj.postconditions : null;
+                            const stateChanges = post && isPlainObject(post.state_changes) ? post.state_changes : null;
+                            const pre = isPlainObject(obj.preconditions) ? obj.preconditions : null;
+                            const characterStates = pre && isPlainObject(pre.character_states) ? pre.character_states : null;
+                            if (stateChanges && Object.keys(stateChanges).length > 0) {
+                                if (!characterStates) {
+                                    throw new NovelCliError(`Invalid ${rel}: missing preconditions.character_states required by chain propagation from ${prevRel}.`, 2);
+                                }
+                                for (const characterKey of Object.keys(stateChanges)) {
+                                    if (!(characterKey in characterStates)) {
+                                        throw new NovelCliError(`Invalid ${rel}: preconditions.character_states missing '${characterKey}' (required by ${prevRel}.postconditions.state_changes).`, 2);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        if (args.step.phase === "commit") {
+            throw new NovelCliError(`Use 'novel commit --volume ${volume}' for commit.`, 2);
+        }
+        await requireVolumePlanArtifacts();
+        const storylinesByChapter = await parseOutlineStorylineIds();
+        const scheduleRaw = await readJsonFile(join(args.rootDir, rels.storylineScheduleJson));
+        validateSchedule(scheduleRaw, storylinesByChapter);
+        // JSON existence + basic schema.
+        const foreshadowingRaw = await readJsonFile(join(args.rootDir, rels.foreshadowingJson));
+        validateForeshadowingPlan(foreshadowingRaw);
+        const newCharsRaw = await readJsonFile(join(args.rootDir, rels.newCharactersJson));
+        validateNewCharacters(newCharsRaw);
+        await validateContracts(storylinesByChapter);
+        return { ok: true, step: stepId, warnings };
     }
+    if (args.step.kind !== "chapter")
+        throw new NovelCliError(`Unsupported step: ${stepId}`, 2);
     const rel = chapterRelPaths(args.step.chapter);
     if (args.step.stage === "draft") {
         const absChapter = join(args.rootDir, rel.staging.chapterMd);

package/dist/volume-commit.js

@@ -0,0 +1,101 @@
+import { rename } from "node:fs/promises";
+import { join } from "node:path";
+import { readCheckpoint, writeCheckpoint } from "./checkpoint.js";
+import { NovelCliError } from "./errors.js";
+import { ensureDir, pathExists, removePath } from "./fs-utils.js";
+import { withWriteLock } from "./lock.js";
+import { validateStep } from "./validate.js";
+import { volumeFinalRelPaths, volumeStagingRelPaths } from "./volume-planning.js";
+async function doRenameDir(rootDir, fromRel, toRel) {
+    const fromAbs = join(rootDir, fromRel);
+    const toAbs = join(rootDir, toRel);
+    if (await pathExists(toAbs)) {
+        throw new NovelCliError(`Refusing to overwrite existing destination: ${toRel}`, 2);
+    }
+    await ensureDir(join(rootDir, "volumes"));
+    try {
+        await rename(fromAbs, toAbs);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new NovelCliError(`Failed to move '${fromRel}' to '${toRel}': ${message}`, 2);
+    }
+}
+function requireVolume(volume) {
+    if (!Number.isInteger(volume) || volume < 1) {
+        throw new NovelCliError(`Invalid --volume: ${String(volume)} (expected int >= 1).`, 2);
+    }
+}
+function requireCheckpointReady(checkpoint, volume) {
+    if (checkpoint.current_volume !== volume) {
+        throw new NovelCliError(`Volume mismatch: checkpoint.current_volume=${checkpoint.current_volume}, but commit requested --volume ${volume}.`, 2);
+    }
+    if (checkpoint.orchestrator_state !== "VOL_PLANNING") {
+        throw new NovelCliError(`Cannot commit volume plan unless orchestrator_state=VOL_PLANNING (got ${checkpoint.orchestrator_state}).`, 2);
+    }
+    const stage = checkpoint.pipeline_stage ?? null;
+    const inflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+    if (!(stage === null || stage === "committed") || inflight !== null) {
+        throw new NovelCliError(`Cannot commit volume plan unless chapter pipeline is idle (pipeline_stage=null|committed and inflight_chapter=null). Got pipeline_stage=${stage ?? "null"} inflight_chapter=${inflight ?? "null"}.`, 2);
+    }
+    if (checkpoint.volume_pipeline_stage !== "commit") {
+        throw new NovelCliError(`Cannot commit volume plan unless volume_pipeline_stage=commit (got ${String(checkpoint.volume_pipeline_stage ?? "null")}). Advance volume steps first.`, 2);
+    }
+}
+export async function commitVolume(args) {
+    requireVolume(args.volume);
+    const plan = [];
+    const warnings = [];
+    const staging = volumeStagingRelPaths(args.volume).dir;
+    const finalDir = volumeFinalRelPaths(args.volume).dir;
+    plan.push(`MOVE ${staging} -> ${finalDir}`);
+    plan.push(`CLEAN staging/foreshadowing`);
+    plan.push(`UPDATE .checkpoint.json (orchestrator_state=WRITING)`);
+    if (args.dryRun) {
+        return { plan, warnings };
+    }
+    await withWriteLock(args.rootDir, {}, async () => {
+        const checkpoint = await readCheckpoint(args.rootDir);
+        requireCheckpointReady(checkpoint, args.volume);
+        const stagingAbs = join(args.rootDir, staging);
+        const finalAbs = join(args.rootDir, finalDir);
+        const stagingExists = await pathExists(stagingAbs);
+        const finalExists = await pathExists(finalAbs);
+        if (finalExists && !stagingExists) {
+            const required = join(args.rootDir, volumeFinalRelPaths(args.volume).outlineMd);
+            if (!(await pathExists(required))) {
+                throw new NovelCliError(`Commit recovery refused: final volume directory exists but is missing ${volumeFinalRelPaths(args.volume).outlineMd}. Resolve manually.`, 2);
+            }
+            warnings.push(`Volume directory already exists (${finalDir}); treating as already committed and only normalizing checkpoint.`);
+        }
+        else if (finalExists && stagingExists) {
+            throw new NovelCliError(`Commit conflict: both staging and final volume directories exist (${staging} and ${finalDir}). Refusing to overwrite; resolve manually.`, 2);
+        }
+        else if (!stagingExists) {
+            throw new NovelCliError(`Missing staging volume directory: ${staging}`, 2);
+        }
+        else {
+            await validateStep({ rootDir: args.rootDir, checkpoint, step: { kind: "volume", phase: "validate" } });
+            await doRenameDir(args.rootDir, staging, finalDir);
+        }
+        const updated = { ...checkpoint };
+        updated.orchestrator_state = "WRITING";
+        updated.volume_pipeline_stage = null;
+        updated.last_committed_volume = args.volume;
+        updated.pipeline_stage = "committed";
+        updated.inflight_chapter = null;
+        updated.revision_count = 0;
+        updated.hook_fix_count = 0;
+        updated.title_fix_count = 0;
+        updated.last_checkpoint_time = new Date().toISOString();
+        await writeCheckpoint(args.rootDir, updated);
+        try {
+            await removePath(join(args.rootDir, "staging/foreshadowing"));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warnings.push(`Failed to clean staging/foreshadowing after commit (non-fatal): ${message}`);
+        }
+    });
+    return { plan, warnings };
+}

package/dist/volume-planning.js

@@ -0,0 +1,143 @@
+import { join } from "node:path";
+import { NovelCliError } from "./errors.js";
+import { pathExists } from "./fs-utils.js";
+import { formatStepId, pad2, pad3 } from "./steps.js";
+export const CHAPTERS_PER_VOLUME = 30;
+export function volumeForChapter(chapter) {
+    if (!Number.isInteger(chapter) || chapter < 1) {
+        throw new NovelCliError(`Invalid chapter: ${String(chapter)} (expected int >= 1).`, 2);
+    }
+    return Math.ceil(chapter / CHAPTERS_PER_VOLUME);
+}
+export function computeVolumeChapterRange(args) {
+    const volume = args.current_volume;
+    const planStart = args.last_completed_chapter + 1;
+    const planEnd = volume * CHAPTERS_PER_VOLUME;
+    if (planStart > planEnd) {
+        throw new NovelCliError(`Invalid volume chapter range: plan_start=${planStart} > plan_end=${planEnd}. Fix .checkpoint.json (current_volume=${volume}, last_completed_chapter=${args.last_completed_chapter}).`, 2);
+    }
+    return { start: planStart, end: planEnd };
+}
+export function volumeStagingRelPaths(volume) {
+    const dir = `staging/volumes/vol-${pad2(volume)}`;
+    const chapterContractsDir = `${dir}/chapter-contracts`;
+    return {
+        dir,
+        outlineMd: `${dir}/outline.md`,
+        storylineScheduleJson: `${dir}/storyline-schedule.json`,
+        foreshadowingJson: `${dir}/foreshadowing.json`,
+        newCharactersJson: `${dir}/new-characters.json`,
+        chapterContractsDir,
+        chapterContractJson: (chapter) => `${chapterContractsDir}/chapter-${pad3(chapter)}.json`
+    };
+}
+export function volumeFinalRelPaths(volume) {
+    const dir = `volumes/vol-${pad2(volume)}`;
+    const chapterContractsDir = `${dir}/chapter-contracts`;
+    return {
+        dir,
+        outlineMd: `${dir}/outline.md`,
+        storylineScheduleJson: `${dir}/storyline-schedule.json`,
+        foreshadowingJson: `${dir}/foreshadowing.json`,
+        newCharactersJson: `${dir}/new-characters.json`,
+        chapterContractsDir,
+        chapterContractJson: (chapter) => `${chapterContractsDir}/chapter-${pad3(chapter)}.json`
+    };
+}
+function normalizeVolumePipelineStage(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (value === "outline" || value === "validate" || value === "commit")
+        return value;
+    return null;
+}
+async function hasAllPlanningArtifacts(args) {
+    const rels = volumeStagingRelPaths(args.volume);
+    const hasOutline = await pathExists(join(args.rootDir, rels.outlineMd));
+    const hasSchedule = await pathExists(join(args.rootDir, rels.storylineScheduleJson));
+    const hasForeshadowing = await pathExists(join(args.rootDir, rels.foreshadowingJson));
+    const hasNewCharacters = await pathExists(join(args.rootDir, rels.newCharactersJson));
+    const hasContractsDir = await pathExists(join(args.rootDir, rels.chapterContractsDir));
+    let missingContracts = 0;
+    const contractPresenceSample = [];
+    for (let ch = args.range.start; ch <= args.range.end; ch++) {
+        const exists = await pathExists(join(args.rootDir, rels.chapterContractJson(ch)));
+        if (!exists)
+            missingContracts += 1;
+        if (contractPresenceSample.length < 3)
+            contractPresenceSample.push({ chapter: ch, exists });
+    }
+    const ok = hasOutline && hasSchedule && hasForeshadowing && hasNewCharacters && hasContractsDir && missingContracts === 0;
+    return {
+        ok,
+        evidence: {
+            volume: args.volume,
+            chapter_range: [args.range.start, args.range.end],
+            staging: {
+                hasOutline,
+                hasSchedule,
+                hasForeshadowing,
+                hasNewCharacters,
+                hasContractsDir,
+                missingContracts,
+                contractPresenceSample
+            }
+        }
+    };
+}
+export async function computeVolumeNextStep(rootDir, checkpoint) {
+    const stage = normalizeVolumePipelineStage(checkpoint.volume_pipeline_stage);
+    const stageIdle = checkpoint.pipeline_stage ?? null;
+    const inflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+    if ((stageIdle === null || stageIdle === "committed") && inflight !== null) {
+        throw new NovelCliError(`Checkpoint inconsistent for VOL_PLANNING: pipeline_stage=${stageIdle ?? "null"} but inflight_chapter=${inflight}. Set inflight_chapter to null.`, 2);
+    }
+    if (stageIdle !== null && stageIdle !== "committed") {
+        throw new NovelCliError(`Checkpoint inconsistent for VOL_PLANNING: pipeline_stage=${stageIdle} (expected null or committed). Finish the chapter pipeline or repair .checkpoint.json.`, 2);
+    }
+    const volume = checkpoint.current_volume;
+    const range = computeVolumeChapterRange({ current_volume: volume, last_completed_chapter: checkpoint.last_completed_chapter });
+    const artifacts = await hasAllPlanningArtifacts({ rootDir, volume, range });
+    if (stage === null || stage === "outline") {
+        return {
+            step: formatStepId({ kind: "volume", phase: "outline" }),
+            reason: artifacts.ok ? "vol_planning:outline:artifacts_present" : "vol_planning:outline",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence: artifacts.evidence
+        };
+    }
+    if (stage === "validate") {
+        if (!artifacts.ok) {
+            return {
+                step: formatStepId({ kind: "volume", phase: "outline" }),
+                reason: "vol_planning:validate:missing_artifacts",
+                inflight: { chapter: null, pipeline_stage: null },
+                evidence: artifacts.evidence
+            };
+        }
+        return {
+            step: formatStepId({ kind: "volume", phase: "validate" }),
+            reason: "vol_planning:validate",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence: artifacts.evidence
+        };
+    }
+    if (stage === "commit") {
+        if (!artifacts.ok) {
+            return {
+                step: formatStepId({ kind: "volume", phase: "outline" }),
+                reason: "vol_planning:commit:missing_artifacts",
+                inflight: { chapter: null, pipeline_stage: null },
+                evidence: artifacts.evidence
+            };
+        }
+        return {
+            step: formatStepId({ kind: "volume", phase: "commit" }),
+            reason: "vol_planning:commit",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence: artifacts.evidence
+        };
+    }
+    // normalizeVolumePipelineStage() ensures the above is exhaustive.
+    throw new NovelCliError(`Unsupported volume_pipeline_stage: ${String(checkpoint.volume_pipeline_stage)}`, 2);
+}