novel-writer-cli 0.0.3 → 0.1.0

package/dist/volume-review.js

@@ -0,0 +1,448 @@
+import { join } from "node:path";
+import { NovelCliError } from "./errors.js";
+import { pathExists, readJsonFile, readTextFile } from "./fs-utils.js";
+import { tryResolveVolumeChapterRange } from "./consistency-auditor.js";
+import { formatStepId, pad2, pad3 } from "./steps.js";
+import { isPlainObject } from "./type-guards.js";
+export const VOL_REVIEW_RELS = {
+    dir: "staging/vol-review",
+    qualitySummary: "staging/vol-review/quality-summary.json",
+    auditReport: "staging/vol-review/audit-report.json",
+    reviewReport: "staging/vol-review/review-report.md",
+    foreshadowStatus: "staging/vol-review/foreshadow-status.json"
+};
+function safeFiniteNumber(v) {
+    if (typeof v !== "number")
+        return null;
+    if (!Number.isFinite(v))
+        return null;
+    return v;
+}
+function safeInt(v) {
+    if (typeof v !== "number")
+        return null;
+    if (!Number.isInteger(v))
+        return null;
+    return v;
+}
+function safeBool(v) {
+    if (typeof v !== "boolean")
+        return null;
+    return v;
+}
+function safeString(v) {
+    if (typeof v !== "string")
+        return null;
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeForeshadowFile(raw) {
+    let obj = raw;
+    if (Array.isArray(obj))
+        obj = { foreshadowing: obj };
+    if (!isPlainObject(obj))
+        return null;
+    const list = obj.foreshadowing;
+    if (!Array.isArray(list))
+        return null;
+    const items = [];
+    for (const it of list) {
+        if (!isPlainObject(it))
+            continue;
+        const id = safeString(it.id);
+        if (!id)
+            continue;
+        items.push({ ...it, id });
+    }
+    return { foreshadowing: items };
+}
+export async function collectVolumeData(args) {
+    const volume = args.checkpoint.current_volume;
+    const endChapter = args.checkpoint.last_completed_chapter;
+    if (!Number.isInteger(volume) || volume < 1)
+        throw new NovelCliError(`Invalid checkpoint.current_volume: ${String(volume)}`, 2);
+    if (!Number.isInteger(endChapter) || endChapter < 0)
+        throw new NovelCliError(`Invalid checkpoint.last_completed_chapter: ${String(endChapter)}`, 2);
+    const warnings = [];
+    const resolvedRange = (await tryResolveVolumeChapterRange({ rootDir: args.rootDir, volume })) ??
+        (endChapter >= 1 ? { start: Math.max(1, endChapter - 9), end: endChapter } : null);
+    if (!resolvedRange) {
+        return {
+            schema_version: 1,
+            generated_at: new Date().toISOString(),
+            as_of: { volume, chapter: endChapter },
+            chapter_range: [0, 0],
+            stats: { chapters_total: 0, chapters_with_eval: 0, overall_avg: null, overall_min: null, overall_max: null },
+            chapters: [],
+            low_chapters: [],
+            warnings: endChapter === 0 ? ["No committed chapters yet; volume review summary is empty."] : ["Unable to resolve chapter range for volume review."]
+        };
+    }
+    const chapterRange = [resolvedRange.start, resolvedRange.end];
+    const chapters = [];
+    const scores = [];
+    const lowChapters = [];
+    for (let chapter = resolvedRange.start; chapter <= resolvedRange.end; chapter++) {
+        const evalRel = `evaluations/chapter-${pad3(chapter)}-eval.json`;
+        const evalAbs = join(args.rootDir, evalRel);
+        const exists = await pathExists(evalAbs);
+        if (!exists) {
+            warnings.push(`Missing eval file: ${evalRel}`);
+            chapters.push({
+                chapter,
+                eval_path: evalRel,
+                overall_final: null,
+                gate_decision: null,
+                revisions: null,
+                force_passed: null,
+                has_high_confidence_violation: null
+            });
+            continue;
+        }
+        let raw;
+        try {
+            raw = await readJsonFile(evalAbs);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warnings.push(`Failed to read ${evalRel}: ${message}`);
+            chapters.push({
+                chapter,
+                eval_path: evalRel,
+                overall_final: null,
+                gate_decision: null,
+                revisions: null,
+                force_passed: null,
+                has_high_confidence_violation: null
+            });
+            continue;
+        }
+        if (!isPlainObject(raw)) {
+            warnings.push(`Invalid eval JSON (expected object): ${evalRel}`);
+            chapters.push({
+                chapter,
+                eval_path: evalRel,
+                overall_final: null,
+                gate_decision: null,
+                revisions: null,
+                force_passed: null,
+                has_high_confidence_violation: null
+            });
+            continue;
+        }
+        const obj = raw;
+        const overall = safeFiniteNumber(obj.overall_final) ??
+            safeFiniteNumber(obj.overall) ??
+            (isPlainObject(obj.judges) ? safeFiniteNumber(obj.judges.overall_final) : null);
+        const gate = isPlainObject(obj.metadata) && isPlainObject(obj.metadata.gate)
+            ? obj.metadata.gate
+            : isPlainObject(obj.gate)
+                ? obj.gate
+                : null;
+        const gate_decision = gate ? safeString(gate.decision) : null;
+        const revisions = gate ? safeInt(gate.revisions) : null;
+        const force_passed = gate ? safeBool(gate.force_passed) : null;
+        const has_high_confidence_violation = gate ? safeBool(gate.has_high_confidence_violation) : null;
+        if (overall !== null) {
+            scores.push(overall);
+            if (overall < 3.5)
+                lowChapters.push({ chapter, overall_final: overall });
+        }
+        chapters.push({
+            chapter,
+            eval_path: evalRel,
+            overall_final: overall,
+            gate_decision,
+            revisions,
+            force_passed,
+            has_high_confidence_violation
+        });
+    }
+    const avg = scores.length > 0 ? scores.reduce((a, b) => a + b, 0) / scores.length : null;
+    const min = scores.length > 0 ? Math.min(...scores) : null;
+    const max = scores.length > 0 ? Math.max(...scores) : null;
+    lowChapters.sort((a, b) => a.overall_final - b.overall_final || a.chapter - b.chapter);
+    return {
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        as_of: { volume, chapter: endChapter },
+        chapter_range: chapterRange,
+        stats: {
+            chapters_total: resolvedRange.end - resolvedRange.start + 1,
+            chapters_with_eval: scores.length,
+            overall_avg: avg === null ? null : Number(avg.toFixed(4)),
+            overall_min: min,
+            overall_max: max
+        },
+        chapters,
+        low_chapters: lowChapters,
+        warnings
+    };
+}
+export async function computeForeshadowingAudit(args) {
+    const volume = args.checkpoint.current_volume;
+    const asOfChapter = args.checkpoint.last_completed_chapter;
+    const warnings = [];
+    const globalRel = "foreshadowing/global.json";
+    const volumeRel = `volumes/vol-${pad2(volume)}/foreshadowing.json`;
+    const globalAbs = join(args.rootDir, globalRel);
+    const volumeAbs = join(args.rootDir, volumeRel);
+    const globalRaw = (await pathExists(globalAbs)) ? await readJsonFile(globalAbs).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(`Failed to read ${globalRel}: ${message}`);
+        return null;
+    }) : null;
+    const volumeRaw = (await pathExists(volumeAbs)) ? await readJsonFile(volumeAbs).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(`Failed to read ${volumeRel}: ${message}`);
+        return null;
+    }) : null;
+    const global = globalRaw === null ? null : normalizeForeshadowFile(globalRaw);
+    const plan = volumeRaw === null ? null : normalizeForeshadowFile(volumeRaw);
+    if (globalRaw !== null && !global)
+        warnings.push(`Invalid ${globalRel}: expected a list or {foreshadowing:[...]}.`);
+    if (volumeRaw !== null && !plan)
+        warnings.push(`Invalid ${volumeRel}: expected a list or {foreshadowing:[...]}.`);
+    const globalItems = global?.foreshadowing ?? [];
+    const planItems = plan?.foreshadowing ?? [];
+    const globalIndex = new Map(globalItems.map((it) => [it.id, it]));
+    const activeCount = globalItems.filter((it) => String(it.status ?? "") !== "resolved").length;
+    const resolvedCount = globalItems.filter((it) => String(it.status ?? "") === "resolved").length;
+    const overdueShort = [];
+    for (const it of globalItems) {
+        const scope = safeString(it.scope);
+        const status = safeString(it.status);
+        if (scope !== "short")
+            continue;
+        if (status === "resolved")
+            continue;
+        const trRaw = it.target_resolve_range;
+        if (!Array.isArray(trRaw) || trRaw.length !== 2)
+            continue;
+        const start = safeInt(trRaw[0]);
+        const end = safeInt(trRaw[1]);
+        if (start === null || end === null)
+            continue;
+        if (asOfChapter > end) {
+            overdueShort.push({ id: it.id, target_resolve_range: [start, end], as_of_chapter: asOfChapter });
+        }
+    }
+    const planMissingInGlobal = [];
+    const planResolvedInGlobal = [];
+    for (const it of planItems) {
+        const existing = globalIndex.get(it.id);
+        if (!existing)
+            planMissingInGlobal.push(it.id);
+        else if (safeString(existing.status) === "resolved")
+            planResolvedInGlobal.push(it.id);
+    }
+    planMissingInGlobal.sort();
+    planResolvedInGlobal.sort();
+    return {
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        as_of: { volume, chapter: asOfChapter },
+        global: { total: globalItems.length, active_count: activeCount, resolved_count: resolvedCount },
+        overdue_short: overdueShort,
+        plan: plan ? { planned_total: planItems.length, missing_in_global: planMissingInGlobal, resolved_in_global: planResolvedInGlobal } : null,
+        warnings
+    };
+}
+export async function computeBridgeCheck(args) {
+    const warnings = [];
+    const storylinesRel = "storylines/storylines.json";
+    const abs = join(args.rootDir, storylinesRel);
+    if (!(await pathExists(abs))) {
+        return {
+            schema_version: 1,
+            generated_at: new Date().toISOString(),
+            volume: args.volume,
+            broken: [],
+            warnings: [`Missing optional file: ${storylinesRel}`]
+        };
+    }
+    let raw;
+    try {
+        raw = await readJsonFile(abs);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            schema_version: 1,
+            generated_at: new Date().toISOString(),
+            volume: args.volume,
+            broken: [],
+            warnings: [`Failed to read ${storylinesRel}: ${message}`]
+        };
+    }
+    if (!isPlainObject(raw)) {
+        return {
+            schema_version: 1,
+            generated_at: new Date().toISOString(),
+            volume: args.volume,
+            broken: [],
+            warnings: [`Invalid ${storylinesRel}: expected JSON object.`]
+        };
+    }
+    const obj = raw;
+    const relsRaw = obj.relationships;
+    if (!Array.isArray(relsRaw)) {
+        return {
+            schema_version: 1,
+            generated_at: new Date().toISOString(),
+            volume: args.volume,
+            broken: [],
+            warnings
+        };
+    }
+    const idExists = (id) => args.foreshadowIds.global.has(id) || args.foreshadowIds.plan.has(id);
+    const broken = [];
+    for (const rel of relsRaw) {
+        if (!isPlainObject(rel))
+            continue;
+        const from = safeString(rel.from);
+        const to = safeString(rel.to);
+        const type = safeString(rel.type);
+        const bridges = rel.bridges;
+        if (!isPlainObject(bridges))
+            continue;
+        const shared = bridges.shared_foreshadowing;
+        if (!Array.isArray(shared))
+            continue;
+        for (const idRaw of shared) {
+            const id = safeString(idRaw);
+            if (!id)
+                continue;
+            if (idExists(id))
+                continue;
+            broken.push({
+                missing_id: id,
+                relationship: { from, to, type }
+            });
+        }
+    }
+    broken.sort((a, b) => String(a.missing_id ?? "").localeCompare(String(b.missing_id ?? "")));
+    return {
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        volume: args.volume,
+        broken,
+        warnings
+    };
+}
+export async function computeStorylineRhythm(args) {
+    const warnings = [];
+    const scheduleRel = `volumes/vol-${pad2(args.volume)}/storyline-schedule.json`;
+    const scheduleAbs = join(args.rootDir, scheduleRel);
+    if (!(await pathExists(scheduleAbs))) {
+        warnings.push(`Missing optional file: ${scheduleRel}`);
+    }
+    else {
+        // Best-effort parse schedule: we only use it as a presence signal for now.
+        try {
+            await readJsonFile(scheduleAbs);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warnings.push(`Failed to read ${scheduleRel}: ${message}`);
+        }
+    }
+    const appearances = new Map();
+    const lastSeen = new Map();
+    const [start, end] = args.chapter_range;
+    const re = /storyline_id:\s*([a-zA-Z0-9_-]+)/gu;
+    for (let chapter = start; chapter <= end; chapter++) {
+        const rel = `summaries/chapter-${pad3(chapter)}-summary.md`;
+        const abs = join(args.rootDir, rel);
+        if (!(await pathExists(abs)))
+            continue;
+        let text;
+        try {
+            text = await readTextFile(abs);
+        }
+        catch {
+            continue;
+        }
+        const idsThisChapter = new Set();
+        for (const m of text.matchAll(re)) {
+            const id = m[1] ?? "";
+            if (!id)
+                continue;
+            idsThisChapter.add(id);
+        }
+        if (idsThisChapter.size === 0)
+            continue;
+        for (const id of idsThisChapter) {
+            appearances.set(id, (appearances.get(id) ?? 0) + 1);
+            lastSeen.set(id, chapter);
+        }
+    }
+    const appearancesObj = {};
+    const lastSeenObj = {};
+    for (const [k, v] of appearances.entries())
+        appearancesObj[k] = v;
+    for (const [k, v] of lastSeen.entries())
+        lastSeenObj[k] = v;
+    return {
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        volume: args.volume,
+        chapter_range: args.chapter_range,
+        appearances: appearancesObj,
+        last_seen: lastSeenObj,
+        warnings
+    };
+}
+export async function computeReviewNextStep(projectRootDir, checkpoint) {
+    const qualitySummaryAbs = join(projectRootDir, VOL_REVIEW_RELS.qualitySummary);
+    const auditReportAbs = join(projectRootDir, VOL_REVIEW_RELS.auditReport);
+    const reviewReportAbs = join(projectRootDir, VOL_REVIEW_RELS.reviewReport);
+    const foreshadowAbs = join(projectRootDir, VOL_REVIEW_RELS.foreshadowStatus);
+    const hasQualitySummary = await pathExists(qualitySummaryAbs);
+    const hasAuditReport = await pathExists(auditReportAbs);
+    const hasReviewReport = await pathExists(reviewReportAbs);
+    const hasForeshadowStatus = await pathExists(foreshadowAbs);
+    const evidence = { hasQualitySummary, hasAuditReport, hasReviewReport, hasForeshadowStatus };
+    if (!hasQualitySummary) {
+        return {
+            step: formatStepId({ kind: "review", phase: "collect" }),
+            reason: "vol_review:missing_quality_summary",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    if (!hasAuditReport) {
+        return {
+            step: formatStepId({ kind: "review", phase: "audit" }),
+            reason: "vol_review:missing_audit_report",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    if (!hasReviewReport) {
+        return {
+            step: formatStepId({ kind: "review", phase: "report" }),
+            reason: "vol_review:missing_review_report",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    if (!hasForeshadowStatus) {
+        return {
+            step: formatStepId({ kind: "review", phase: "cleanup" }),
+            reason: "vol_review:missing_foreshadow_status",
+            inflight: { chapter: null, pipeline_stage: null },
+            evidence
+        };
+    }
+    return {
+        step: formatStepId({ kind: "review", phase: "transition" }),
+        reason: "vol_review:ready_transition",
+        inflight: { chapter: null, pipeline_stage: null },
+        evidence
+    };
+}
+// Alias for tasks wording.
+export async function computeReviewNext(projectRootDir, checkpoint) {
+    return await computeReviewNextStep(projectRootDir, checkpoint);
+}

package/docs/user/novel-cli.md

@@ -23,6 +23,7 @@
 | `novel validate <step>` | 校验 step 产物是否齐全/合规 |
 | `novel advance <step>` | 校验通过后推进 checkpoint |
 | `novel commit --chapter N` | 提交 staging 事务到正式目录（写入） |
+| `novel commit --volume N` | 提交卷规划 staging 产物到 `volumes/`（写入） |
 | `novel lock status/clear` | 查看/清理写入锁（解决中断导致的 stale lock） |
 | `novel promises init/report` | 承诺台账：初始化与窗口报告 |
 | `novel engagement report` | 参与度密度：窗口报告 |
@@ -190,6 +191,34 @@ novel lock clear
 
 > 常见场景：执行器在写入阶段中断（断电/kill/异常退出），留下 stale lock；此时可先 `novel lock status` 确认，再执行 `novel lock clear`。
 
+## 卷规划（VOL_PLANNING）
+
+当 `.checkpoint.json.orchestrator_state == "VOL_PLANNING"` 时，`novel next` 会进入卷规划三步流水线：
+
+```bash
+novel next
+# volume:outline
+
+novel instructions volume:outline --json
+# 运行 PlotArchitect，写入 staging/volumes/vol-XX/**
+
+novel validate volume:outline
+novel advance volume:outline
+
+novel next
+# volume:validate
+
+novel instructions volume:validate --json
+novel validate volume:validate
+novel advance volume:validate
+
+novel next
+# volume:commit
+
+novel instructions volume:commit --json
+novel commit --volume <N>
+```
+
 ## 角色语气漂移（M7H.3，可选）
 
 角色语气漂移用于：为关键角色建立“台词基线画像”，并在后续章节检测偏移，生成纠偏指令 `character-voice-drift.json`，直到恢复为止（自动清除）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novel-writer-cli",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Executor-agnostic novel orchestration CLI",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,8 @@
   "homepage": "https://github.com/DankerMu/novel-writer-cli#readme",
   "scripts": {
     "dev": "tsx src/cli.ts",
-    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "start": "node dist/cli.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/schemas/platform-profile.schema.json

@@ -133,6 +133,11 @@
       "properties": {
         "genre_drive_type": { "$ref": "#/$defs/genre_drive_type" },
         "weight_profile_id": { "type": "string", "minLength": 1 },
+        "max_revisions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Max gate-driven revision/polish loops before forcing progression."
+        },
         "weight_overrides": {
           "type": "object",
           "description": "Optional per-dimension weight overrides (dimension_name -> weight).",