novel-writer-cli 0.0.3 → 0.1.0

package/dist/cli.js

@@ -1,24 +1,28 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from "commander";
 import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { buildCharacterVoiceProfiles, clearCharacterVoiceDriftFile, computeCharacterVoiceDrift, loadActiveCharacterVoiceDriftIds, loadCharacterVoiceProfiles, writeCharacterVoiceDriftFile, writeCharacterVoiceProfilesFile } from "./character-voice.js";
 import { NovelCliError } from "./errors.js";
 import { errJson, okJson, printJson } from "./output.js";
-import { pathExists } from "./fs-utils.js";
+import { pathExists, readJsonFile, writeJsonFile, writeTextFile } from "./fs-utils.js";
 import { resolveProjectRoot } from "./project.js";
 import { readCheckpoint } from "./checkpoint.js";
 import { initProject, normalizePlatformId, resolveInitRootDir } from "./init.js";
 import { advanceCheckpointForStep } from "./advance.js";
 import { commitChapter } from "./commit.js";
+import { commitVolume } from "./volume-commit.js";
 import { buildInstructionPacket } from "./instructions.js";
 import { getLockStatus, clearStaleLock, withWriteLock } from "./lock.js";
 import { computeNextStep } from "./next-step.js";
 import { computeEngagementReport, loadEngagementMetricsStream, writeEngagementLogs } from "./engagement.js";
 import { computePromiseLedgerReport, ensurePromiseLedgerInitialized, loadPromiseLedger, writePromiseLedgerLogs } from "./promise-ledger.js";
-import { parseStepId } from "./steps.js";
+import { pad2, pad3, parseStepId } from "./steps.js";
+import { isPlainObject } from "./type-guards.js";
 import { validateStep } from "./validate.js";
+import { VOL_REVIEW_RELS, collectVolumeData, computeBridgeCheck, computeForeshadowingAudit, computeStorylineRhythm } from "./volume-review.js";
+import { tryResolveVolumeChapterRange } from "./consistency-auditor.js";
 function detectCommandName(argv) {
     for (const token of argv) {
         if (token === "--")
@@ -95,7 +99,7 @@ function buildProgram(argv) {
             return;
         }
         process.stdout.write(`Project: ${rootDir}\n`);
-        process.stdout.write(`Checkpoint: chapter=${checkpoint.last_completed_chapter} volume=${checkpoint.current_volume}\n`);
+        process.stdout.write(`Checkpoint: state=${checkpoint.orchestrator_state} chapter=${checkpoint.last_completed_chapter} volume=${checkpoint.current_volume}\n`);
         process.stdout.write(`Pipeline: stage=${checkpoint.pipeline_stage ?? "null"} inflight=${checkpoint.inflight_chapter ?? "null"} revisions=${checkpoint.revision_count ?? 0} hook_fixes=${checkpoint.hook_fix_count ?? 0} title_fixes=${checkpoint.title_fix_count ?? 0}\n`);
         if (lock.exists) {
             process.stdout.write(`Lock: present${lock.stale ? " (stale)" : ""} started=${lock.info?.started ?? "unknown"} pid=${lock.info?.pid ?? "unknown"} chapter=${lock.info?.chapter ?? "unknown"}\n`);
@@ -187,13 +191,24 @@ function buildProgram(argv) {
     program
         .command("commit")
         .description("Commit staging artifacts into final locations (transaction).")
-        .requiredOption("--chapter <n>", "Chapter number to commit.", (v) => Number.parseInt(String(v), 10))
+        .option("--chapter <n>", "Chapter number to commit.", (v) => Number.parseInt(String(v), 10))
+        .option("--volume <n>", "Volume number to commit (volume planning artifacts).", (v) => Number.parseInt(String(v), 10))
         .option("--dry-run", "Show planned actions without applying them.")
         .action(async (localOpts) => {
         const opts = program.opts();
         const json = Boolean(opts.json);
         const rootDir = await resolveProjectRoot({ cwd: process.cwd(), projectOverride: opts.project });
-        const result = await commitChapter({ rootDir, chapter: localOpts.chapter, dryRun: Boolean(localOpts.dryRun) });
+        const chapter = localOpts.chapter;
+        const volume = localOpts.volume;
+        if (chapter !== undefined && volume !== undefined) {
+            throw new NovelCliError("Invalid commit: provide exactly one of --chapter or --volume.", 2);
+        }
+        if (chapter === undefined && volume === undefined) {
+            throw new NovelCliError("Invalid commit: missing required option --chapter or --volume.", 2);
+        }
+        const result = chapter !== undefined
+            ? await commitChapter({ rootDir, chapter, dryRun: Boolean(localOpts.dryRun) })
+            : await commitVolume({ rootDir, volume: volume, dryRun: Boolean(localOpts.dryRun) });
         if (json) {
             printJson(okJson("commit", { rootDir, ...result }));
             return;
@@ -204,8 +219,187 @@ function buildProgram(argv) {
             for (const w of result.warnings)
                 process.stdout.write(`WARN: ${w}\n`);
         }
-        if (!localOpts.dryRun)
-            process.stdout.write(`Committed chapter ${localOpts.chapter}.\n`);
+        if (!localOpts.dryRun) {
+            if (chapter !== undefined)
+                process.stdout.write(`Committed chapter ${chapter}.\n`);
+            else
+                process.stdout.write(`Committed volume ${volume}.\n`);
+        }
+    });
+    const volumeReview = program.command("volume-review").description("Volume-end review helper commands (issue #144).");
+    volumeReview
+        .command("collect")
+        .description(`Generate ${VOL_REVIEW_RELS.qualitySummary} from committed evals (best-effort).`)
+        .action(async () => {
+        const opts = program.opts();
+        const json = Boolean(opts.json);
+        const rootDir = await resolveProjectRoot({ cwd: process.cwd(), projectOverride: opts.project });
+        const result = await withWriteLock(rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(rootDir);
+            const summary = await collectVolumeData({ rootDir, checkpoint });
+            await writeJsonFile(join(rootDir, VOL_REVIEW_RELS.qualitySummary), summary);
+            return { checkpoint, summary };
+        });
+        if (json) {
+            printJson(okJson("volume-review collect", { rootDir, rel: VOL_REVIEW_RELS.qualitySummary, summary: result.summary }));
+            return;
+        }
+        process.stdout.write(`Wrote ${VOL_REVIEW_RELS.qualitySummary}.\n`);
+    });
+    volumeReview
+        .command("report")
+        .description(`Generate ${VOL_REVIEW_RELS.reviewReport} from quality summary + audit report (deterministic markdown).`)
+        .action(async () => {
+        const opts = program.opts();
+        const json = Boolean(opts.json);
+        const rootDir = await resolveProjectRoot({ cwd: process.cwd(), projectOverride: opts.project });
+        await withWriteLock(rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(rootDir);
+            const volume = checkpoint.current_volume;
+            const endChapter = checkpoint.last_completed_chapter;
+            const resolvedRange = (await tryResolveVolumeChapterRange({ rootDir, volume })) ??
+                (Number.isInteger(endChapter) && endChapter >= 1 ? { start: Math.max(1, endChapter - 9), end: endChapter } : null);
+            if (!resolvedRange) {
+                throw new NovelCliError(`Cannot resolve volume review chapter_range (last_completed_chapter=${String(endChapter)}).`, 2);
+            }
+            // Best-effort reads: validation guards presence.
+            let summary = null;
+            let audit = null;
+            try {
+                summary = await readJsonFile(join(rootDir, VOL_REVIEW_RELS.qualitySummary));
+            }
+            catch {
+                summary = null;
+            }
+            try {
+                audit = await readJsonFile(join(rootDir, VOL_REVIEW_RELS.auditReport));
+            }
+            catch {
+                audit = null;
+            }
+            const lines = [];
+            lines.push(`# Volume Review Report`);
+            lines.push("");
+            lines.push(`- volume: ${volume}`);
+            lines.push(`- chapter_range: ${resolvedRange.start}-${resolvedRange.end}`);
+            if (isPlainObject(summary)) {
+                const stats = isPlainObject(summary.stats)
+                    ? summary.stats
+                    : null;
+                if (stats) {
+                    const avg = typeof stats.overall_avg === "number" ? stats.overall_avg : null;
+                    const min = typeof stats.overall_min === "number" ? stats.overall_min : null;
+                    const max = typeof stats.overall_max === "number" ? stats.overall_max : null;
+                    lines.push(`- overall_avg: ${avg ?? "n/a"} (min=${min ?? "n/a"}, max=${max ?? "n/a"})`);
+                }
+                const lows = Array.isArray(summary.low_chapters)
+                    ? summary.low_chapters
+                    : [];
+                if (lows.length > 0) {
+                    lines.push("");
+                    lines.push(`## Low Score Chapters (<3.5)`);
+                    for (const it of lows.slice(0, 20)) {
+                        if (!isPlainObject(it))
+                            continue;
+                        const ch = it.chapter;
+                        const sc = it.overall_final;
+                        if (typeof ch === "number" && typeof sc === "number")
+                            lines.push(`- ch${pad3(ch)}: ${sc}`);
+                    }
+                }
+            }
+            if (isPlainObject(audit)) {
+                const stats = isPlainObject(audit.stats) ? audit.stats : null;
+                if (stats) {
+                    const total = typeof stats.issues_total === "number" ? stats.issues_total : null;
+                    lines.push("");
+                    lines.push(`## Consistency Audit`);
+                    lines.push(`- issues_total: ${total ?? "n/a"}`);
+                }
+            }
+            await writeTextFile(join(rootDir, VOL_REVIEW_RELS.reviewReport), `${lines.join("\n")}\n`);
+        });
+        if (json) {
+            printJson(okJson("volume-review report", { rootDir, rel: VOL_REVIEW_RELS.reviewReport }));
+            return;
+        }
+        process.stdout.write(`Wrote ${VOL_REVIEW_RELS.reviewReport}.\n`);
+    });
+    volumeReview
+        .command("cleanup")
+        .description(`Generate ${VOL_REVIEW_RELS.foreshadowStatus} (foreshadowing audit + bridge check + storyline rhythm).`)
+        .action(async () => {
+        const opts = program.opts();
+        const json = Boolean(opts.json);
+        const rootDir = await resolveProjectRoot({ cwd: process.cwd(), projectOverride: opts.project });
+        const payload = await withWriteLock(rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(rootDir);
+            const volume = checkpoint.current_volume;
+            const endChapter = checkpoint.last_completed_chapter;
+            const resolvedRange = (await tryResolveVolumeChapterRange({ rootDir, volume })) ??
+                (Number.isInteger(endChapter) && endChapter >= 1 ? { start: Math.max(1, endChapter - 9), end: endChapter } : null);
+            if (!resolvedRange) {
+                throw new NovelCliError(`Cannot resolve volume review chapter_range (last_completed_chapter=${String(endChapter)}).`, 2);
+            }
+            const foreshadowingAudit = await computeForeshadowingAudit({ rootDir, checkpoint });
+            // Best-effort: compute bridge check using available foreshadow ids.
+            const globalIds = new Set();
+            const planIds = new Set();
+            try {
+                const globalRaw = await readJsonFile(join(rootDir, "foreshadowing/global.json"));
+                const list = Array.isArray(globalRaw)
+                    ? globalRaw
+                    : isPlainObject(globalRaw) && Array.isArray(globalRaw.foreshadowing)
+                        ? globalRaw.foreshadowing
+                        : [];
+                for (const it of list) {
+                    if (!isPlainObject(it))
+                        continue;
+                    const id = typeof it.id === "string" ? it.id.trim() : "";
+                    if (id)
+                        globalIds.add(id);
+                }
+            }
+            catch {
+                // optional
+            }
+            try {
+                const rel = `volumes/vol-${pad2(volume)}/foreshadowing.json`;
+                const planRaw = await readJsonFile(join(rootDir, rel));
+                const list = Array.isArray(planRaw)
+                    ? planRaw
+                    : isPlainObject(planRaw) && Array.isArray(planRaw.foreshadowing)
+                        ? planRaw.foreshadowing
+                        : [];
+                for (const it of list) {
+                    if (!isPlainObject(it))
+                        continue;
+                    const id = typeof it.id === "string" ? it.id.trim() : "";
+                    if (id)
+                        planIds.add(id);
+                }
+            }
+            catch {
+                // optional
+            }
+            const bridgeCheck = await computeBridgeCheck({ rootDir, volume, foreshadowIds: { global: globalIds, plan: planIds } });
+            const rhythm = await computeStorylineRhythm({ rootDir, volume, chapter_range: [resolvedRange.start, resolvedRange.end] });
+            const out = {
+                schema_version: 1,
+                generated_at: new Date().toISOString(),
+                as_of: { volume, chapter: endChapter },
+                foreshadowing_audit: foreshadowingAudit,
+                bridge_check: bridgeCheck,
+                storyline_rhythm: rhythm
+            };
+            await writeJsonFile(join(rootDir, VOL_REVIEW_RELS.foreshadowStatus), out);
+            return out;
+        });
+        if (json) {
+            printJson(okJson("volume-review cleanup", { rootDir, rel: VOL_REVIEW_RELS.foreshadowStatus, payload }));
+            return;
+        }
+        process.stdout.write(`Wrote ${VOL_REVIEW_RELS.foreshadowStatus}.\n`);
     });
     const promises = program.command("promises").description("Promise ledger (long-horizon narrative promises).");
     promises

package/dist/commit.js

@@ -1249,6 +1249,7 @@ export async function commitChapter(args) {
             }
             updatedCheckpoint.pipeline_stage = "committed";
             updatedCheckpoint.inflight_chapter = null;
+            updatedCheckpoint.orchestrator_state = "WRITING";
             updatedCheckpoint.revision_count = 0;
             updatedCheckpoint.hook_fix_count = 0;
             updatedCheckpoint.title_fix_count = 0;

package/dist/fs-utils.js

@@ -1,5 +1,5 @@
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { NovelCliError } from "./errors.js";
 export async function pathExists(path) {
     try {
@@ -55,7 +55,22 @@ export async function writeTextFileIfMissing(path, contents) {
     }
 }
 export async function writeJsonFile(path, payload) {
-    await writeTextFile(path, `${JSON.stringify(payload, null, 2)}\n`);
+    const content = `${JSON.stringify(payload, null, 2)}\n`;
+    const tmp = join(dirname(path), `.${process.pid}.tmp`);
+    try {
+        await ensureDir(dirname(path));
+        await writeFile(tmp, content, "utf8");
+        await rename(tmp, path);
+    }
+    catch (err) {
+        // Best-effort cleanup of temp file on failure.
+        try {
+            await rm(tmp, { force: true });
+        }
+        catch { /* ignore */ }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new NovelCliError(`Failed to write file: ${path}. ${message}`);
+    }
 }
 export async function removePath(path) {
     try {

package/dist/gate-decision.js

@@ -0,0 +1,59 @@
+import { isPlainObject } from "./type-guards.js";
+export const GATE_DECISIONS = ["pass", "polish", "revise", "pause_for_user", "pause_for_user_force_rewrite", "force_passed"];
+function isHighViolation(check) {
+    return check.status === "violation" && check.confidence === "high";
+}
+export function detectHighConfidenceViolation(evalRaw) {
+    if (!isPlainObject(evalRaw))
+        return { has_high_confidence_violation: false, high_confidence_violations: [] };
+    const evalObj = evalRaw;
+    const cvRaw = evalObj.contract_verification;
+    if (!isPlainObject(cvRaw))
+        return { has_high_confidence_violation: false, high_confidence_violations: [] };
+    const cv = cvRaw;
+    const pick = (key) => {
+        const raw = cv[key];
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((it) => isPlainObject(it));
+    };
+    const hardChecks = [];
+    for (const key of ["l1_checks", "l2_checks", "l3_checks"]) {
+        for (const it of pick(key)) {
+            if (!isHighViolation(it))
+                continue;
+            hardChecks.push(it);
+        }
+    }
+    for (const it of pick("ls_checks")) {
+        if (!isHighViolation(it))
+            continue;
+        const constraintType = typeof it.constraint_type === "string" ? it.constraint_type : null;
+        // Default to hard when missing to preserve safety.
+        const isHard = constraintType === null || constraintType === "hard";
+        if (!isHard)
+            continue;
+        hardChecks.push(constraintType === null ? { ...it, constraint_type_inferred: true } : it);
+    }
+    return { has_high_confidence_violation: hardChecks.length > 0, high_confidence_violations: hardChecks };
+}
+export function computeGateDecision(args) {
+    const maxRevisions = typeof args.max_revisions === "number" && Number.isInteger(args.max_revisions) && args.max_revisions >= 0 ? args.max_revisions : 2;
+    if (args.force_pass)
+        return "force_passed";
+    if (args.has_high_confidence_violation) {
+        return args.revision_count >= maxRevisions ? "pause_for_user" : "revise";
+    }
+    const score = args.overall_final;
+    if (!Number.isFinite(score))
+        return "pause_for_user_force_rewrite";
+    if (score >= 4.0)
+        return "pass";
+    if (score >= 3.5)
+        return args.revision_count >= maxRevisions ? "force_passed" : "polish";
+    if (score >= 3.0)
+        return args.revision_count >= maxRevisions ? "force_passed" : "revise";
+    if (score >= 2.0)
+        return "pause_for_user";
+    return "pause_for_user_force_rewrite";
+}

package/dist/init.js

@@ -106,6 +106,8 @@ const STAGING_SUBDIRS = [
     "staging/evaluations",
     "staging/logs",
     "staging/storylines",
+    "staging/volumes",
+    "staging/foreshadowing",
     "staging/manifests"
 ];
 export async function initProject(args) {