novel-writer-cli 0.1.0 → 0.2.1

package/dist/__tests__/quickstart-pipeline.test.js

@@ -0,0 +1,346 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { advanceCheckpointForStep } from "../advance.js";
+import { readCheckpoint } from "../checkpoint.js";
+import { buildInstructionPacket } from "../instructions.js";
+import { computeNextStep } from "../next-step.js";
+async function writeText(absPath, contents) {
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, contents, "utf8");
+}
+async function writeJson(absPath, payload) {
+    await writeText(absPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+async function pathExists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+test("advance quickstart:world transitions INIT -> QUICK_START", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-init-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "INIT",
+        pipeline_stage: null,
+        inflight_chapter: null
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), {
+        rules: [
+            {
+                id: "W-001",
+                category: "magic_system",
+                rule: "力量体系上限为九阶。",
+                constraint_type: "hard",
+                exceptions: [],
+                introduced_chapter: null,
+                last_verified: null
+            }
+        ]
+    });
+    const updated = await advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "world" } });
+    assert.equal(updated.orchestrator_state, "QUICK_START");
+    assert.equal(updated.quickstart_phase, "world");
+    const checkpoint = await readCheckpoint(rootDir);
+    assert.equal(checkpoint.orchestrator_state, "QUICK_START");
+    assert.equal(checkpoint.quickstart_phase, "world");
+});
+test("advance quickstart:characters writes quickstart_phase correctly", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-characters-advance-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    const updated = await advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "characters" } });
+    assert.equal(updated.orchestrator_state, "QUICK_START");
+    assert.equal(updated.quickstart_phase, "characters");
+    const checkpoint = await readCheckpoint(rootDir);
+    assert.equal(checkpoint.orchestrator_state, "QUICK_START");
+    assert.equal(checkpoint.quickstart_phase, "characters");
+});
+test("advance quickstart:style writes quickstart_phase correctly", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-style-advance-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    const updated = await advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "style" } });
+    assert.equal(updated.orchestrator_state, "QUICK_START");
+    assert.equal(updated.quickstart_phase, "style");
+    const checkpoint = await readCheckpoint(rootDir);
+    assert.equal(checkpoint.orchestrator_state, "QUICK_START");
+    assert.equal(checkpoint.quickstart_phase, "style");
+});
+test("advance quickstart:trial writes quickstart_phase correctly", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-trial-advance-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    await writeText(join(rootDir, "staging/quickstart/trial-chapter.md"), "# Trial\n\nText\n");
+    const updated = await advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "trial" } });
+    assert.equal(updated.orchestrator_state, "QUICK_START");
+    assert.equal(updated.quickstart_phase, "trial");
+    const checkpoint = await readCheckpoint(rootDir);
+    assert.equal(checkpoint.orchestrator_state, "QUICK_START");
+    assert.equal(checkpoint.quickstart_phase, "trial");
+});
+test("advance quickstart rejects wrong orchestrator_state", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-advance-wrong-state-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "WRITING",
+        pipeline_stage: null,
+        inflight_chapter: null
+    });
+    await assert.rejects(() => advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "world" } }), /Cannot advance quickstart:world unless orchestrator_state=INIT or QUICK_START/);
+});
+test("computeNextStep recovers quickstart phase from staging artifacts", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-resume-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null
+    });
+    // No artifacts yet → world
+    let next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:world");
+    // rules.json present → characters
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:characters");
+    // contracts dir + one contract → style
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:style");
+    // style profile present → trial
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:trial");
+    // trial chapter present → results
+    await writeText(join(rootDir, "staging/quickstart/trial-chapter.md"), `# 试写章\n\n（测试）\n`);
+    next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:results");
+    assert.equal(next.reason, "quickstart:results");
+    // evaluation present → results (ready to advance/commit)
+    await writeJson(join(rootDir, "staging/quickstart/evaluation.json"), { overall: 4.2, recommendation: "pass" });
+    next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:results");
+    assert.equal(next.reason, "quickstart:results:artifacts_present");
+});
+test("computeNextStep allows redoing current quickstart phase when artifacts are missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-recover-checkpoint-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        quickstart_phase: "world"
+    });
+    const next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:world");
+    assert.equal(next.reason, "quickstart:world");
+});
+test("computeNextStep blocks quickstart rollback when quickstart_phase=characters but world artifacts are missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-recover-characters-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        quickstart_phase: "characters"
+    });
+    const next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:world");
+    assert.match(next.reason, /quickstart:recovery_blocked/);
+    assert.equal(next.evidence.recovery_blocked.checkpoint_phase, "characters");
+    assert.equal(next.evidence.recovery_blocked.inferred_phase, "world");
+    assert.equal(next.evidence.recovery_blocked.expected_path, "staging/quickstart/rules.json");
+});
+test("computeNextStep allows redoing style phase when style profile is missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-recover-style-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        quickstart_phase: "style"
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    const next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:style");
+    assert.equal(next.reason, "quickstart:style");
+});
+test("computeNextStep allows redoing trial phase when trial chapter is missing", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-recover-trial-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        quickstart_phase: "trial"
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    const next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:trial");
+    assert.equal(next.reason, "quickstart:trial");
+});
+test("computeNextStep continues forward when checkpoint quickstart_phase is consistent with staging artifacts", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-recover-happy-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        quickstart_phase: "style"
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    const next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "quickstart:trial");
+    assert.equal(next.reason, "quickstart:trial");
+    assert.equal(next.evidence.recovery_blocked ?? null, null);
+});
+test("buildInstructionPacket (quickstart) includes NOVEL_ASK gate when provided", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-novel-ask-"));
+    const questionSpec = {
+        version: 1,
+        topic: "quickstart_gate",
+        questions: [
+            {
+                id: "genre",
+                header: "Genre",
+                question: "Pick a genre.",
+                kind: "single_choice",
+                required: true,
+                options: [{ label: "xuanhuan", description: "玄幻" }]
+            }
+        ]
+    };
+    const answerPath = "staging/novel-ask/quickstart.json";
+    const built = (await buildInstructionPacket({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "INIT" },
+        step: { kind: "quickstart", phase: "world" },
+        embedMode: null,
+        writeManifest: false,
+        novelAskGate: { novel_ask: questionSpec, answer_path: answerPath }
+    }));
+    assert.equal(built.packet.step, "quickstart:world");
+    assert.equal(built.packet.answer_path, answerPath);
+    assert.equal(built.packet.novel_ask.topic, questionSpec.topic);
+    assert.equal(built.packet.expected_outputs[0].path, answerPath);
+});
+test("advance quickstart:results commits artifacts and transitions to VOL_PLANNING", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-commit-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        volume_pipeline_stage: null
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), {
+        rules: [
+            {
+                id: "W-001",
+                category: "magic_system",
+                rule: "力量体系上限为九阶。",
+                constraint_type: "hard",
+                exceptions: [],
+                introduced_chapter: null,
+                last_verified: null
+            }
+        ]
+    });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    await writeText(join(rootDir, "staging/quickstart/trial-chapter.md"), `# 试写章\n\n（测试）\n`);
+    await writeJson(join(rootDir, "staging/quickstart/evaluation.json"), { overall: 4.2, recommendation: "pass" });
+    const updated = await advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "results" } });
+    assert.equal(updated.orchestrator_state, "VOL_PLANNING");
+    assert.equal(updated.volume_pipeline_stage, null);
+    assert.equal(updated.quickstart_phase ?? null, null);
+    // Staging quickstart cleared
+    assert.equal(await pathExists(join(rootDir, "staging/quickstart")), false);
+    // Final artifacts exist
+    assert.equal(await pathExists(join(rootDir, "world/rules.json")), true);
+    assert.equal(await pathExists(join(rootDir, "style-profile.json")), true);
+    assert.equal(await pathExists(join(rootDir, "characters/active/hero.json")), true);
+    assert.equal(await pathExists(join(rootDir, "logs/quickstart/trial-chapter.md")), true);
+    assert.equal(await pathExists(join(rootDir, "logs/quickstart/evaluation.json")), true);
+    // Pipeline now in volume planning and should not re-enter quickstart.
+    const next = await computeNextStep(rootDir, await readCheckpoint(rootDir));
+    assert.equal(next.step, "volume:outline");
+});
+test("advance quickstart:results validates all contracts (not just a slice)", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-quickstart-contracts-all-"));
+    await writeJson(join(rootDir, ".checkpoint.json"), {
+        last_completed_chapter: 0,
+        current_volume: 1,
+        orchestrator_state: "QUICK_START",
+        pipeline_stage: null,
+        inflight_chapter: null,
+        volume_pipeline_stage: null
+    });
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), {
+        rules: [
+            {
+                id: "W-001",
+                category: "magic_system",
+                rule: "力量体系上限为九阶。",
+                constraint_type: "hard",
+                exceptions: [],
+                introduced_chapter: null,
+                last_verified: null
+            }
+        ]
+    });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    await writeText(join(rootDir, "staging/quickstart/trial-chapter.md"), `# 试写章\n\n（测试）\n`);
+    await writeJson(join(rootDir, "staging/quickstart/evaluation.json"), { overall: 4.2, recommendation: "pass" });
+    for (let i = 1; i <= 10; i++) {
+        const id = String(i).padStart(2, "0");
+        await writeJson(join(rootDir, `staging/quickstart/contracts/contract-${id}.json`), { id: `c-${id}`, display_name: `角色${id}`, contracts: [] });
+    }
+    // 11th contract is invalid: validate:results must still catch it.
+    await writeJson(join(rootDir, "staging/quickstart/contracts/contract-11.json"), []);
+    await assert.rejects(() => advanceCheckpointForStep({ rootDir, step: { kind: "quickstart", phase: "results" } }), /Invalid contract JSON/);
+});

package/dist/__tests__/safe-path-symlink.test.js

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { resolveProjectRelativePath } from "../safe-path.js";
+test("resolveProjectRelativePath rejects symlink escapes outside project root", async (t) => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-safe-path-root-"));
+    const outsideDir = await mkdtemp(join(tmpdir(), "novel-safe-path-outside-"));
+    await writeFile(join(outsideDir, "payload.json"), "{}\n", "utf8");
+    await mkdir(join(rootDir, "staging"), { recursive: true });
+    try {
+        await symlink(outsideDir, join(rootDir, "staging/evil"), "dir");
+    }
+    catch (err) {
+        const code = err instanceof Error ? err.code : null;
+        if (code === "EPERM" || code === "EACCES" || code === "ENOTSUP" || code === "ENOSYS") {
+            t.skip(`symlink not permitted in this environment: ${code}`);
+            return;
+        }
+        throw err;
+    }
+    assert.throws(() => resolveProjectRelativePath(rootDir, "staging/evil/payload.json", "testPath"), /Unsafe path outside project root/);
+});
+test("resolveProjectRelativePath rejects symlink escapes for non-existent write targets", async (t) => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-safe-path-root-write-"));
+    const outsideDir = await mkdtemp(join(tmpdir(), "novel-safe-path-outside-write-"));
+    await mkdir(join(rootDir, "staging"), { recursive: true });
+    try {
+        await symlink(outsideDir, join(rootDir, "staging/evil"), "dir");
+    }
+    catch (err) {
+        const code = err instanceof Error ? err.code : null;
+        if (code === "EPERM" || code === "EACCES" || code === "ENOTSUP" || code === "ENOSYS") {
+            t.skip(`symlink not permitted in this environment: ${code}`);
+            return;
+        }
+        throw err;
+    }
+    assert.throws(() => resolveProjectRelativePath(rootDir, "staging/evil/subdir/newfile.json", "testPath"), /Unsafe path outside project root/);
+});

package/dist/__tests__/validate-quickstart-prereqs.test.js

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { validateStep } from "../validate.js";
+async function writeText(absPath, contents) {
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, contents, "utf8");
+}
+async function writeJson(absPath, payload) {
+    await writeText(absPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+test("validateStep(quickstart:characters) requires rules.json", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-validate-quickstart-characters-"));
+    await assert.rejects(() => validateStep({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "QUICK_START" },
+        step: { kind: "quickstart", phase: "characters" }
+    }), /Missing required file: staging\/quickstart\/rules\.json/);
+});
+test("validateStep(quickstart:style) requires contracts dir", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-validate-quickstart-style-"));
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await assert.rejects(() => validateStep({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "QUICK_START" },
+        step: { kind: "quickstart", phase: "style" }
+    }), /Missing required file: staging\/quickstart\/contracts/);
+});
+test("validateStep(quickstart:characters) rejects empty contracts dir", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-validate-quickstart-empty-contracts-"));
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await mkdir(join(rootDir, "staging/quickstart/contracts"), { recursive: true });
+    await assert.rejects(() => validateStep({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "QUICK_START" },
+        step: { kind: "quickstart", phase: "characters" }
+    }), /expected at least 1 \*\.json contract file/);
+});
+test("validateStep(quickstart:style) rejects invalid style source_type", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-validate-quickstart-invalid-style-"));
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "banana" });
+    await assert.rejects(() => validateStep({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "QUICK_START" },
+        step: { kind: "quickstart", phase: "style" }
+    }), /Invalid staging\/quickstart\/style-profile\.json: source_type must be one of:/);
+});
+test("validateStep(quickstart:trial) requires style-profile.json", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-validate-quickstart-trial-"));
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await assert.rejects(() => validateStep({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "QUICK_START" },
+        step: { kind: "quickstart", phase: "trial" }
+    }), /Missing required file: staging\/quickstart\/style-profile\.json/);
+});
+test("validateStep(quickstart:trial) rejects empty trial chapter", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-validate-quickstart-empty-trial-"));
+    await writeJson(join(rootDir, "staging/quickstart/rules.json"), { rules: [] });
+    await writeJson(join(rootDir, "staging/quickstart/contracts/hero.json"), { id: "hero", display_name: "阿宁", contracts: [] });
+    await writeJson(join(rootDir, "staging/quickstart/style-profile.json"), { source_type: "template" });
+    await writeText(join(rootDir, "staging/quickstart/trial-chapter.md"), "");
+    await assert.rejects(() => validateStep({
+        rootDir,
+        checkpoint: { last_completed_chapter: 0, current_volume: 1, orchestrator_state: "QUICK_START" },
+        step: { kind: "quickstart", phase: "trial" }
+    }), /Empty draft file: staging\/quickstart\/trial-chapter\.md/);
+});

package/dist/advance.js

@@ -1,8 +1,10 @@
-import { join } from "node:path";
+import { copyFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { readCheckpoint, writeCheckpoint } from "./checkpoint.js";
 import { NovelCliError } from "./errors.js";
-import { removePath } from "./fs-utils.js";
+import { ensureDir, pathExists, removePath } from "./fs-utils.js";
 import { withWriteLock } from "./lock.js";
+import { QUICKSTART_FINAL_RELS, QUICKSTART_STAGING_RELS } from "./quickstart.js";
 import { chapterRelPaths, formatStepId, titleFixSnapshotRel } from "./steps.js";
 import { validateStep } from "./validate.js";
 import { VOL_REVIEW_RELS } from "./volume-review.js";
@@ -109,6 +111,88 @@ export async function advanceCheckpointForStep(args) {
             return updated;
         });
     }
+    if (step.kind === "quickstart") {
+        const qsStep = step;
+        const copyFileSafe = async (fromRel, toRel) => {
+            const fromAbs = join(args.rootDir, fromRel);
+            const toAbs = join(args.rootDir, toRel);
+            await ensureDir(dirname(toAbs));
+            await copyFile(fromAbs, toAbs);
+        };
+        const commitQuickStartArtifacts = async () => {
+            // Core artifacts
+            const requiredRelPaths = [
+                QUICKSTART_STAGING_RELS.rulesJson,
+                QUICKSTART_STAGING_RELS.styleProfileJson,
+                QUICKSTART_STAGING_RELS.trialChapterMd,
+                QUICKSTART_STAGING_RELS.evaluationJson
+            ];
+            for (const rel of requiredRelPaths) {
+                const abs = join(args.rootDir, rel);
+                if (!(await pathExists(abs)))
+                    throw new NovelCliError(`Missing required file: ${rel}`, 2);
+            }
+            await copyFileSafe(QUICKSTART_STAGING_RELS.rulesJson, QUICKSTART_FINAL_RELS.worldRulesJson);
+            await copyFileSafe(QUICKSTART_STAGING_RELS.styleProfileJson, QUICKSTART_FINAL_RELS.styleProfileJson);
+            await copyFileSafe(QUICKSTART_STAGING_RELS.trialChapterMd, QUICKSTART_FINAL_RELS.trialChapterMd);
+            await copyFileSafe(QUICKSTART_STAGING_RELS.evaluationJson, QUICKSTART_FINAL_RELS.evaluationJson);
+            // Contracts dir → characters/active/*.json (overwrite by filename).
+            const contractsAbs = join(args.rootDir, QUICKSTART_STAGING_RELS.contractsDir);
+            if (!(await pathExists(contractsAbs)))
+                throw new NovelCliError(`Missing required directory: ${QUICKSTART_STAGING_RELS.contractsDir}`, 2);
+            const entries = await readdir(contractsAbs, { withFileTypes: true });
+            const jsonFiles = entries.filter((e) => e.isFile() && e.name.endsWith(".json")).map((e) => e.name).sort();
+            if (jsonFiles.length === 0) {
+                throw new NovelCliError(`Invalid ${QUICKSTART_STAGING_RELS.contractsDir}: expected at least 1 *.json contract file.`, 2);
+            }
+            const activeDirAbs = join(args.rootDir, QUICKSTART_FINAL_RELS.charactersActiveDir);
+            await ensureDir(activeDirAbs);
+            for (const name of jsonFiles) {
+                await copyFile(join(contractsAbs, name), join(activeDirAbs, name));
+            }
+        };
+        return await withWriteLock(args.rootDir, {}, async () => {
+            const checkpoint = await readCheckpoint(args.rootDir);
+            if (checkpoint.orchestrator_state !== "INIT" && checkpoint.orchestrator_state !== "QUICK_START") {
+                throw new NovelCliError(`Cannot advance ${formatStepId(qsStep)} unless orchestrator_state=INIT or QUICK_START.`, 2);
+            }
+            const stage = checkpoint.pipeline_stage ?? null;
+            const inflight = typeof checkpoint.inflight_chapter === "number" ? checkpoint.inflight_chapter : null;
+            if (inflight !== null) {
+                throw new NovelCliError(`Checkpoint inconsistent for QUICK_START advance: inflight_chapter=${inflight} (expected null). Finish the chapter pipeline or repair .checkpoint.json.`, 2);
+            }
+            if (stage !== null && stage !== "committed") {
+                throw new NovelCliError(`Checkpoint inconsistent for QUICK_START advance: pipeline_stage=${stage} (expected null or committed). Finish the chapter pipeline or repair .checkpoint.json.`, 2);
+            }
+            // Enforce validate-before-advance to keep deterministic semantics.
+            await validateStep({ rootDir: args.rootDir, checkpoint, step: qsStep });
+            const updated = { ...checkpoint };
+            updated.inflight_chapter = null;
+            updated.pipeline_stage = null;
+            updated.quickstart_phase = qsStep.phase;
+            if (qsStep.phase === "results") {
+                await commitQuickStartArtifacts();
+                updated.orchestrator_state = "VOL_PLANNING";
+                updated.volume_pipeline_stage = null;
+                updated.quickstart_phase = null;
+            }
+            else {
+                updated.orchestrator_state = "QUICK_START";
+            }
+            updated.last_checkpoint_time = new Date().toISOString();
+            await writeCheckpoint(args.rootDir, updated);
+            if (qsStep.phase === "results") {
+                // Best-effort cleanup: keep artifacts committed even if staging removal fails.
+                try {
+                    await removePath(join(args.rootDir, QUICKSTART_STAGING_RELS.dir));
+                }
+                catch {
+                    // ignore
+                }
+            }
+            return updated;
+        });
+    }
     if (step.kind === "review") {
         const reviewStep = step;
         return await withWriteLock(args.rootDir, {}, async () => {
@@ -168,5 +252,6 @@ export async function advanceCheckpointForStep(args) {
             return updated;
         });
     }
-    throw new NovelCliError(`Unsupported step kind: ${step.kind}`, 2);
+    // parseStepId ensures this is exhaustive.
+    throw new NovelCliError(`Unsupported step kind.`, 2);
 }

package/dist/checkpoint.js

@@ -1,17 +1,17 @@
 import { join } from "node:path";
 import { NovelCliError } from "./errors.js";
 import { readJsonFile, writeJsonFile } from "./fs-utils.js";
-import { ORCHESTRATOR_STATES, VOLUME_PHASES } from "./steps.js";
+import { ORCHESTRATOR_STATES, QUICKSTART_PHASES, VOLUME_PHASES } from "./steps.js";
 import { isPlainObject } from "./type-guards.js";
 export const PIPELINE_STAGES = ["drafting", "drafted", "refined", "judged", "revising", "committed"];
 export function createDefaultCheckpoint(nowIso) {
     return {
         last_completed_chapter: 0,
         current_volume: 1,
-        // TODO(CS-O3): Default to INIT once the quickstart pipeline is implemented.
-        orchestrator_state: "WRITING",
-        pipeline_stage: "committed",
+        orchestrator_state: "INIT",
+        pipeline_stage: null,
         volume_pipeline_stage: null,
+        quickstart_phase: null,
         inflight_chapter: null,
         revision_count: 0,
         hook_fix_count: 0,
@@ -113,6 +113,25 @@ function parseCheckpoint(data) {
     else {
         throw new NovelCliError(`.checkpoint.json.volume_pipeline_stage must be a string (or null)`, 2);
     }
+    const quickstartPhaseRaw = data.quickstart_phase;
+    let quickstartPhase;
+    if (quickstartPhaseRaw === undefined) {
+        quickstartPhase = undefined;
+    }
+    else if (quickstartPhaseRaw === null) {
+        quickstartPhase = null;
+    }
+    else if (typeof quickstartPhaseRaw === "string") {
+        if (QUICKSTART_PHASES.includes(quickstartPhaseRaw)) {
+            quickstartPhase = quickstartPhaseRaw;
+        }
+        else {
+            throw new NovelCliError(`.checkpoint.json.quickstart_phase must be one of: ${QUICKSTART_PHASES.join(", ")} (or null)`, 2);
+        }
+    }
+    else {
+        throw new NovelCliError(`.checkpoint.json.quickstart_phase must be a string (or null)`, 2);
+    }
     const lastCommitted = data.last_committed_volume;
     if (lastCommitted !== undefined) {
         const lc = asInt(lastCommitted);
@@ -174,6 +193,8 @@ function parseCheckpoint(data) {
         checkpoint.pipeline_stage = pipelineStage;
     if (volumeStage !== undefined)
         checkpoint.volume_pipeline_stage = volumeStage;
+    if (quickstartPhase !== undefined)
+        checkpoint.quickstart_phase = quickstartPhase;
     if (inflight !== undefined)
         checkpoint.inflight_chapter = inflight;
     return checkpoint;