novel-writer-cli 0.0.2 → 0.0.3

package/README.md

@@ -46,7 +46,15 @@ node dist/cli.js --help
 
 ## 最小工作流：跑通一章
 
-在**小说项目根目录**（含 `.checkpoint.json`）运行：
+如果你是从零开始，在空目录先执行初始化（会创建 `.checkpoint.json` + `staging/**`，并写入若干可选模板文件）：
+
+```bash
+mkdir my-novel && cd my-novel
+novel init                      # --platform qidian|tomato 可选
+novel status
+```
+
+之后在**小说项目根目录**（含 `.checkpoint.json`）运行：
 
 ```bash
 # 1) 计算下一步

package/dist/__tests__/init.test.js

@@ -0,0 +1,240 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { readCheckpoint } from "../checkpoint.js";
+import { NovelCliError } from "../errors.js";
+import { initProject, normalizePlatformId, resolveInitRootDir } from "../init.js";
+import { computeNextStep } from "../next-step.js";
+import { parsePlatformProfile } from "../platform-profile.js";
+// ── Helpers ──────────────────────────────────────────────────────────────
+async function assertDir(absPath) {
+    const s = await stat(absPath);
+    assert.ok(s.isDirectory(), `Expected directory: ${absPath}`);
+}
+async function assertFile(absPath) {
+    const s = await stat(absPath);
+    assert.ok(s.isFile(), `Expected file: ${absPath}`);
+}
+async function statExists(absPath) {
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(absPath) {
+    return JSON.parse(await readFile(absPath, "utf8"));
+}
+// ── resolveInitRootDir ──────────────────────────────────────────────────
+test("resolveInitRootDir returns cwd when no projectOverride", () => {
+    const result = resolveInitRootDir({ cwd: "/tmp/foo" });
+    assert.equal(result, "/tmp/foo");
+});
+test("resolveInitRootDir resolves relative projectOverride against cwd", () => {
+    const result = resolveInitRootDir({ cwd: "/tmp", projectOverride: "my-novel" });
+    assert.equal(result, "/tmp/my-novel");
+});
+test("resolveInitRootDir rejects path traversal", () => {
+    assert.throws(() => resolveInitRootDir({ cwd: "/tmp", projectOverride: "../../etc" }), (err) => err instanceof NovelCliError && /path traversal/i.test(err.message));
+});
+// ── normalizePlatformId ─────────────────────────────────────────────────
+test("normalizePlatformId accepts valid values", () => {
+    assert.equal(normalizePlatformId("qidian"), "qidian");
+    assert.equal(normalizePlatformId("tomato"), "tomato");
+});
+test("normalizePlatformId rejects invalid values", () => {
+    assert.throws(() => normalizePlatformId("jjwxc"), (err) => err instanceof NovelCliError && /Invalid --platform.*jjwxc/i.test(err.message));
+    assert.throws(() => normalizePlatformId(42), (err) => err instanceof NovelCliError && /Invalid --platform/i.test(err.message));
+});
+// ── initProject: basic skeleton ─────────────────────────────────────────
+test("initProject creates a runnable skeleton with all checkpoint fields", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-basic-"));
+    try {
+        const result = await initProject({ rootDir });
+        assert.equal(result.rootDir, rootDir);
+        // Exact created set (non-minimal = checkpoint + 4 templates)
+        assert.deepEqual(result.created.sort(), [".checkpoint.json", "ai-blacklist.json", "brief.md", "style-profile.json", "web-novel-cliche-lint.json"].sort());
+        // All 7 staging dirs ensured
+        assert.equal(result.ensuredDirs.length, 7);
+        assert.ok(result.ensuredDirs.includes("staging/chapters"));
+        assert.ok(result.ensuredDirs.includes("staging/manifests"));
+        // Verify ALL checkpoint fields
+        const checkpoint = await readCheckpoint(rootDir);
+        assert.equal(checkpoint.last_completed_chapter, 0);
+        assert.equal(checkpoint.current_volume, 1);
+        assert.equal(checkpoint.pipeline_stage, "committed");
+        assert.equal(checkpoint.inflight_chapter, null);
+        assert.equal(checkpoint.revision_count, 0);
+        assert.equal(checkpoint.hook_fix_count, 0);
+        assert.equal(checkpoint.title_fix_count, 0);
+        assert.ok(typeof checkpoint.last_checkpoint_time === "string" && checkpoint.last_checkpoint_time.length > 0);
+        // Integration: next step should be chapter:001:draft
+        const next = await computeNextStep(rootDir, checkpoint);
+        assert.equal(next.step, "chapter:001:draft");
+        // All staging dirs exist
+        for (const relDir of [
+            "staging/chapters",
+            "staging/summaries",
+            "staging/state",
+            "staging/evaluations",
+            "staging/logs",
+            "staging/storylines",
+            "staging/manifests"
+        ]) {
+            await assertDir(join(rootDir, relDir));
+        }
+        // All template files exist
+        for (const relFile of ["brief.md", "style-profile.json", "ai-blacklist.json", "web-novel-cliche-lint.json"]) {
+            await assertFile(join(rootDir, relFile));
+        }
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+// ── Skip / Force: .checkpoint.json ──────────────────────────────────────
+test("initProject does not overwrite .checkpoint.json without --force", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-no-force-"));
+    try {
+        await writeFile(join(rootDir, ".checkpoint.json"), `${JSON.stringify({ last_completed_chapter: 5, current_volume: 1, pipeline_stage: "committed", inflight_chapter: null }, null, 2)}\n`, "utf8");
+        const result = await initProject({ rootDir, minimal: true });
+        assert.ok(result.skipped.includes(".checkpoint.json"));
+        assert.equal(result.overwritten.length, 0);
+        const checkpoint = await readCheckpoint(rootDir);
+        assert.equal(checkpoint.last_completed_chapter, 5);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("initProject overwrites .checkpoint.json with --force", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-force-"));
+    try {
+        await writeFile(join(rootDir, ".checkpoint.json"), `${JSON.stringify({ last_completed_chapter: 5, current_volume: 1, pipeline_stage: "committed", inflight_chapter: null }, null, 2)}\n`, "utf8");
+        const result = await initProject({ rootDir, minimal: true, force: true });
+        assert.ok(result.overwritten.includes(".checkpoint.json"));
+        const checkpoint = await readCheckpoint(rootDir);
+        assert.equal(checkpoint.last_completed_chapter, 0);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+// ── Skip / Force: template files ────────────────────────────────────────
+test("initProject skips existing template files without --force", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-skip-tpl-"));
+    try {
+        // Pre-create a template file
+        await writeFile(join(rootDir, "brief.md"), "custom brief", "utf8");
+        await writeFile(join(rootDir, "ai-blacklist.json"), "{}", "utf8");
+        const result = await initProject({ rootDir });
+        assert.ok(result.skipped.includes("brief.md"));
+        assert.ok(result.skipped.includes("ai-blacklist.json"));
+        assert.ok(result.created.includes("style-profile.json"));
+        assert.ok(result.created.includes("web-novel-cliche-lint.json"));
+        // Verify content was NOT overwritten
+        const content = await readFile(join(rootDir, "brief.md"), "utf8");
+        assert.equal(content, "custom brief");
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+test("initProject overwrites template files with --force", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-force-tpl-"));
+    try {
+        await writeFile(join(rootDir, "brief.md"), "custom brief", "utf8");
+        const result = await initProject({ rootDir, force: true });
+        assert.ok(result.overwritten.includes("brief.md"));
+        // Verify content was overwritten with template content
+        const content = await readFile(join(rootDir, "brief.md"), "utf8");
+        assert.notEqual(content, "custom brief");
+        assert.ok(content.length > 0);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+// ── Platform: tomato ────────────────────────────────────────────────────
+test("initProject writes platform-profile.json + genre-weight-profiles.json for --platform tomato", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-platform-tomato-"));
+    try {
+        const result = await initProject({ rootDir, minimal: true, platform: "tomato" });
+        assert.ok(result.created.includes("platform-profile.json"));
+        assert.ok(result.created.includes("genre-weight-profiles.json"));
+        const raw = await readJson(join(rootDir, "platform-profile.json"));
+        const profile = parsePlatformProfile(raw, "platform-profile.json");
+        assert.equal(profile.platform, "tomato");
+        assert.ok(typeof profile.created_at === "string" && profile.created_at.length > 0);
+        assert.ok(typeof profile.schema_version === "number");
+        // genre-weight-profiles.json should be a valid JSON object
+        const genreRaw = await readJson(join(rootDir, "genre-weight-profiles.json"));
+        assert.ok(typeof genreRaw === "object" && genreRaw !== null && !Array.isArray(genreRaw));
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+// ── Platform: qidian ────────────────────────────────────────────────────
+test("initProject writes platform-profile.json for --platform qidian", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-platform-qidian-"));
+    try {
+        const result = await initProject({ rootDir, minimal: true, platform: "qidian" });
+        assert.ok(result.created.includes("platform-profile.json"));
+        assert.ok(result.created.includes("genre-weight-profiles.json"));
+        const raw = await readJson(join(rootDir, "platform-profile.json"));
+        const profile = parsePlatformProfile(raw, "platform-profile.json");
+        assert.equal(profile.platform, "qidian");
+        assert.ok(typeof profile.created_at === "string" && profile.created_at.length > 0);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+// ── Minimal mode ────────────────────────────────────────────────────────
+test("initProject minimal mode skips templates", async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), "novel-init-minimal-"));
+    try {
+        const result = await initProject({ rootDir, minimal: true });
+        assert.ok(result.created.includes(".checkpoint.json"));
+        assert.equal(result.created.length, 1);
+        await assertFile(join(rootDir, ".checkpoint.json"));
+        await assertDir(join(rootDir, "staging/chapters"));
+        assert.equal(await statExists(join(rootDir, "brief.md")), false);
+        assert.equal(await statExists(join(rootDir, "style-profile.json")), false);
+        assert.equal(await statExists(join(rootDir, "ai-blacklist.json")), false);
+        assert.equal(await statExists(join(rootDir, "web-novel-cliche-lint.json")), false);
+    }
+    finally {
+        await rm(rootDir, { recursive: true, force: true });
+    }
+});
+// ── Non-existent --project directory ────────────────────────────────────
+test("initProject can initialize a non-existent --project directory", async () => {
+    const parentDir = await mkdtemp(join(tmpdir(), "novel-init-project-"));
+    const rootDir = join(parentDir, "child-project");
+    try {
+        const result = await initProject({ rootDir, minimal: true });
+        assert.equal(result.rootDir, rootDir);
+        await assertFile(join(rootDir, ".checkpoint.json"));
+    }
+    finally {
+        await rm(parentDir, { recursive: true, force: true });
+    }
+});
+// ── Negative: rootDir is a file ─────────────────────────────────────────
+test("initProject throws when rootDir is a file", async () => {
+    const parentDir = await mkdtemp(join(tmpdir(), "novel-init-file-"));
+    const filePath = join(parentDir, "not-a-dir");
+    await writeFile(filePath, "hello", "utf8");
+    try {
+        await assert.rejects(() => initProject({ rootDir: filePath, minimal: true }), (err) => err instanceof NovelCliError && /not a directory/i.test(err.message));
+    }
+    finally {
+        await rm(parentDir, { recursive: true, force: true });
+    }
+});

package/dist/checkpoint.js

@@ -3,6 +3,18 @@ import { NovelCliError } from "./errors.js";
 import { readJsonFile, writeJsonFile } from "./fs-utils.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,
+        pipeline_stage: "committed",
+        inflight_chapter: null,
+        revision_count: 0,
+        hook_fix_count: 0,
+        title_fix_count: 0,
+        last_checkpoint_time: nowIso ?? new Date().toISOString()
+    };
+}
 function asInt(value) {
     if (typeof value !== "number")
         return null;

package/dist/cli.js

@@ -9,6 +9,7 @@ import { errJson, okJson, printJson } from "./output.js";
 import { pathExists } 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 { buildInstructionPacket } from "./instructions.js";
@@ -46,6 +47,38 @@ function buildProgram(argv) {
     program.showHelpAfterError(false);
     program.showSuggestionAfterError(false);
     program.exitOverride();
+    program
+        .command("init")
+        .description("Initialize a new novel project directory (.checkpoint.json + staging/** + optional templates).")
+        .option("--force", "Overwrite existing files when present.")
+        .option("--minimal", "Only create .checkpoint.json + staging/** (skip templates).")
+        .option("--platform <id>", "Also write platform-profile.json (+ genre-weight-profiles.json). Supported: qidian|tomato.")
+        .action(async (localOpts) => {
+        const opts = program.opts();
+        const json = Boolean(opts.json);
+        const rootDir = resolveInitRootDir({ cwd: process.cwd(), projectOverride: opts.project });
+        const platform = localOpts.platform ? normalizePlatformId(localOpts.platform) : undefined;
+        const result = await initProject({
+            rootDir,
+            force: Boolean(localOpts.force),
+            minimal: Boolean(localOpts.minimal),
+            platform
+        });
+        if (json) {
+            printJson(okJson("init", result));
+            return;
+        }
+        process.stdout.write(`Project: ${rootDir}\n`);
+        for (const d of result.ensuredDirs)
+            process.stdout.write(`MKDIR ${d}\n`);
+        for (const p of result.created)
+            process.stdout.write(`CREATE ${p}\n`);
+        for (const p of result.overwritten)
+            process.stdout.write(`OVERWRITE ${p}\n`);
+        for (const p of result.skipped)
+            process.stdout.write(`SKIP ${p}\n`);
+        process.stdout.write(`Next: novel next\n`);
+    });
     program
         .command("status")
         .description("Show project status (checkpoint, locks, next action).")

package/dist/init.js

@@ -0,0 +1,163 @@
+import { stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createDefaultCheckpoint } from "./checkpoint.js";
+import { NovelCliError } from "./errors.js";
+import { ensureDir, pathExists, readJsonFile, readTextFile, writeJsonFile, writeTextFile } from "./fs-utils.js";
+import { rejectPathTraversalInput } from "./safe-path.js";
+import { isPlainObject } from "./type-guards.js";
+export function resolveInitRootDir(args) {
+    const cwdAbs = resolve(args.cwd);
+    if (!args.projectOverride)
+        return cwdAbs;
+    rejectPathTraversalInput(args.projectOverride, "--project");
+    return resolve(cwdAbs, args.projectOverride);
+}
+export function normalizePlatformId(value) {
+    if (value === "qidian" || value === "tomato")
+        return value;
+    throw new NovelCliError(`Invalid --platform: ${String(value)} (expected qidian|tomato).`, 2);
+}
+function moduleRootDir() {
+    // src/init.ts → <repo_root>; dist/init.js → <package_root>
+    // NOTE: Not compatible with single-file bundlers (esbuild/rollup).
+    return resolve(fileURLToPath(new URL(".", import.meta.url)), "..");
+}
+const TEMPLATE_DIR = join(moduleRootDir(), "templates");
+async function ensureRootIsDirectory(absPath) {
+    try {
+        const s = await stat(absPath);
+        if (!s.isDirectory()) {
+            throw new NovelCliError(`Project root is not a directory: ${absPath}`, 2);
+        }
+    }
+    catch (err) {
+        if (err instanceof NovelCliError)
+            throw err;
+        // Path does not exist or is inaccessible — attempt to create it.
+        await ensureDir(absPath);
+    }
+}
+async function writeIfMissingOrForce(args) {
+    const abs = join(args.rootDir, args.relPath);
+    const exists = await pathExists(abs);
+    if (exists && !args.force) {
+        args.result.skipped.push(args.relPath);
+        return;
+    }
+    if (args.contents.kind === "text")
+        await writeTextFile(abs, args.contents.text);
+    else
+        await writeJsonFile(abs, args.contents.json);
+    if (exists)
+        args.result.overwritten.push(args.relPath);
+    else
+        args.result.created.push(args.relPath);
+}
+async function loadTemplateText(name) {
+    try {
+        return await readTextFile(join(TEMPLATE_DIR, name));
+    }
+    catch (err) {
+        if (err instanceof NovelCliError) {
+            throw new NovelCliError(`Built-in template missing or unreadable: templates/${name}. ${err.message}`, 2);
+        }
+        throw err;
+    }
+}
+async function loadTemplateJson(name) {
+    let raw;
+    try {
+        raw = await readJsonFile(join(TEMPLATE_DIR, name));
+    }
+    catch (err) {
+        if (err instanceof NovelCliError) {
+            throw new NovelCliError(`Built-in template missing or unreadable: templates/${name}. ${err.message}`, 2);
+        }
+        throw err;
+    }
+    if (!isPlainObject(raw)) {
+        throw new NovelCliError(`Built-in template templates/${name}: expected a JSON object, got ${typeof raw}.`, 2);
+    }
+    return raw;
+}
+async function loadPlatformProfileTemplate(platform) {
+    const raw = await loadTemplateJson("platform-profile.json");
+    const defaults = raw.defaults;
+    if (!isPlainObject(defaults)) {
+        throw new NovelCliError("Invalid templates/platform-profile.json: missing 'defaults' object.", 2);
+    }
+    const selected = defaults[platform];
+    if (!isPlainObject(selected)) {
+        throw new NovelCliError(`Invalid templates/platform-profile.json: missing defaults.${platform} object.`, 2);
+    }
+    return selected;
+}
+const DEFAULT_TEMPLATES = [
+    { relPath: "brief.md", templateName: "brief-template.md", kind: "text" },
+    { relPath: "style-profile.json", templateName: "style-profile-template.json", kind: "json" },
+    { relPath: "ai-blacklist.json", templateName: "ai-blacklist.json", kind: "json" },
+    { relPath: "web-novel-cliche-lint.json", templateName: "web-novel-cliche-lint.json", kind: "json" }
+];
+const STAGING_SUBDIRS = [
+    "staging/chapters",
+    "staging/summaries",
+    "staging/state",
+    "staging/evaluations",
+    "staging/logs",
+    "staging/storylines",
+    "staging/manifests"
+];
+export async function initProject(args) {
+    const force = Boolean(args.force);
+    const minimal = Boolean(args.minimal);
+    const platform = args.platform ?? null;
+    const result = {
+        rootDir: args.rootDir,
+        ensuredDirs: [],
+        created: [],
+        overwritten: [],
+        skipped: []
+    };
+    await ensureRootIsDirectory(args.rootDir);
+    for (const relDir of STAGING_SUBDIRS) {
+        await ensureDir(join(args.rootDir, relDir));
+        result.ensuredDirs.push(relDir);
+    }
+    // Intentionally capture time once for transactional consistency.
+    const nowIso = new Date().toISOString();
+    await writeIfMissingOrForce({
+        rootDir: args.rootDir,
+        relPath: ".checkpoint.json",
+        contents: { kind: "json", json: createDefaultCheckpoint(nowIso) },
+        force,
+        result
+    });
+    if (!minimal) {
+        for (const tmpl of DEFAULT_TEMPLATES) {
+            const contents = tmpl.kind === "text"
+                ? { kind: "text", text: await loadTemplateText(tmpl.templateName) }
+                : { kind: "json", json: await loadTemplateJson(tmpl.templateName) };
+            await writeIfMissingOrForce({ rootDir: args.rootDir, relPath: tmpl.relPath, contents, force, result });
+        }
+    }
+    if (platform) {
+        const templateProfile = await loadPlatformProfileTemplate(platform);
+        await writeIfMissingOrForce({
+            rootDir: args.rootDir,
+            relPath: "platform-profile.json",
+            contents: { kind: "json", json: { ...templateProfile, created_at: nowIso } },
+            force,
+            result
+        });
+        // genre-weight-profiles.json is required when platform-profile.json.scoring is present.
+        await writeIfMissingOrForce({
+            rootDir: args.rootDir,
+            relPath: "genre-weight-profiles.json",
+            contents: { kind: "json", json: await loadTemplateJson("genre-weight-profiles.json") },
+            force,
+            result
+        });
+    }
+    return result;
+}

package/docs/user/novel-cli.md

@@ -16,6 +16,7 @@
 
 | 命令 | 用途 |
 |------|------|
+| `novel init` | 初始化项目骨架（写入 `.checkpoint.json`、创建 `staging/**`，并可选写入模板配置） |
 | `novel status` | 查看 checkpoint / lock / next（只读） |
 | `novel next` | 计算确定性的下一步 step id |
 | `novel instructions <step>` | 输出 instruction packet（JSON） |
@@ -51,6 +52,33 @@ npm run build
 node dist/cli.js --help
 ```
 
+## 初始化项目（init）
+
+`novel` 的大多数命令都要求项目根目录存在 `.checkpoint.json`（用于确定项目边界与当前进度）。从零开始时，先在空目录执行一次：
+
+```bash
+mkdir my-novel && cd my-novel
+novel init --platform tomato
+```
+
+默认会：
+
+- 写入 `.checkpoint.json`
+- 创建 `staging/**` 必要目录
+- 写入若干模板文件（如 `brief.md`、`style-profile.json`、`ai-blacklist.json`、`web-novel-cliche-lint.json`）
+
+常用选项：
+
+- `--minimal`：只创建 `.checkpoint.json` + `staging/**`（跳过模板文件）
+- `--force`：覆盖已有文件（谨慎使用）
+- `--platform qidian|tomato`：写入 `platform-profile.json`，并同时写入 `genre-weight-profiles.json`（用于 QualityJudge 动态权重）
+
+也可指定目标目录（会在目录不存在时创建）：
+
+```bash
+novel init --project ./my-novel --platform tomato
+```
+
 ## 最短路径：跑通“一章的确定性编排”
 
 以下示例假设你已在**小说项目根目录**（含 `.checkpoint.json`），或使用 `--project <dir>` 指定根目录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novel-writer-cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Executor-agnostic novel orchestration CLI",
   "license": "MIT",
   "type": "module",