@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/cli/src/commands/doctor.ts

@@ -0,0 +1,391 @@
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { findProjectRoot, log, logError, GLOBAL_ENV_PATH } from "../utils.js";
+import { fetchWithProxy } from "@actalk/inkos-core";
+import {
+  ensureNodeRuntimePinFiles,
+  evaluateSqliteMemorySupport,
+  inspectNodeRuntimePinFiles,
+} from "../runtime-requirements.js";
+
+function buildDoctorProbePlans(
+  preferredApiFormat: "chat" | "responses" | undefined,
+  preferredStream: boolean | undefined,
+): Array<{ apiFormat: "chat" | "responses"; stream: boolean }> {
+  const plans: Array<{ apiFormat: "chat" | "responses"; stream: boolean }> = [];
+  const seen = new Set<string>();
+  const push = (apiFormat: "chat" | "responses", stream: boolean) => {
+    const key = `${apiFormat}:${stream ? "1" : "0"}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    plans.push({ apiFormat, stream });
+  };
+
+  if (preferredApiFormat) {
+    push(preferredApiFormat, preferredStream ?? false);
+    push(preferredApiFormat, !(preferredStream ?? false));
+  }
+  const alternate = preferredApiFormat === "responses" ? "chat" : "responses";
+  push(alternate, false);
+  push(alternate, true);
+  push("chat", false);
+  push("chat", true);
+  push("responses", false);
+  push("responses", true);
+  return plans;
+}
+
+export function buildDoctorModelCandidates(
+  preferredModel: string | undefined,
+  discoveredModels: Array<{ id: string; name: string }>,
+): string[] {
+  const seen = new Set<string>();
+  const candidates: string[] = [];
+  const push = (value: string | undefined | null) => {
+    if (!value || value.trim().length === 0) return;
+    const model = value.trim();
+    if (seen.has(model)) return;
+    seen.add(model);
+    candidates.push(model);
+  };
+
+  push(preferredModel);
+  for (const model of discoveredModels) push(model.id);
+  push("gpt-5.4");
+  push("gpt-4o");
+  push("claude-sonnet-4-6");
+  push("MiniMax-M2.7");
+  push("kimi-k2.5");
+  push("gemini-2.5-flash");
+  return candidates;
+}
+
+export function resolveDoctorModelsBaseUrl(
+  service: string | undefined,
+  baseUrl: string,
+  resolveServiceModelsBaseUrl: (service: string) => string | undefined,
+): string {
+  if (!service || service.length === 0) {
+    return baseUrl;
+  }
+  return resolveServiceModelsBaseUrl(service) ?? baseUrl;
+}
+
+async function fetchDoctorModels(
+  modelsBaseUrl: string,
+  apiKey: string,
+  proxyUrl?: string,
+): Promise<Array<{ id: string; name: string }>> {
+  const modelsUrl = modelsBaseUrl.replace(/\/$/, "") + "/models";
+  try {
+    const res = await fetchWithProxy(modelsUrl, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    }, proxyUrl);
+    if (!res.ok) return [];
+    const json = await res.json() as { data?: Array<{ id: string }> };
+    return (json.data ?? []).map((model) => ({ id: model.id, name: model.id }));
+  } catch {
+    return [];
+  }
+}
+
+export const doctorCommand = new Command("doctor")
+  .description("Check environment and project health")
+  .option("--repair-node-runtime", "Write .nvmrc and .node-version pinned to Node 22 for this project")
+  .action(async (opts: { repairNodeRuntime?: boolean }) => {
+    const checks: Array<{ name: string; ok: boolean; detail: string }> = [];
+    const root = findProjectRoot();
+
+    if (opts.repairNodeRuntime) {
+      const repair = await ensureNodeRuntimePinFiles(root);
+      checks.push({
+        name: "Node runtime pin files repaired",
+        ok: true,
+        detail: repair.updated
+          ? `Wrote ${repair.written.join(", ")} -> Node 22`
+          : "Already pinned to Node 22",
+      });
+    }
+
+    // 1. Check Node.js version
+    const nodeVersion = process.version;
+    const major = parseInt(nodeVersion.slice(1).split(".")[0]!, 10);
+    checks.push({
+      name: "Node.js >= 20",
+      ok: major >= 20,
+      detail: nodeVersion,
+    });
+    checks.push({
+      name: "SQLite memory index (Node 22+)",
+      ...evaluateSqliteMemorySupport({ nodeVersion }),
+    });
+    checks.push({
+      name: "Node runtime pin files",
+      ...await inspectNodeRuntimePinFiles(root),
+    });
+
+    // 2. Check inkos.json exists
+    try {
+      await readFile(join(root, "inkos.json"), "utf-8");
+      checks.push({ name: "inkos.json", ok: true, detail: "Found" });
+    } catch {
+      checks.push({ name: "inkos.json", ok: false, detail: "Not found. Run 'inkos init'" });
+    }
+
+    // 3. Check .env exists
+    try {
+      await readFile(join(root, ".env"), "utf-8");
+      checks.push({ name: ".env", ok: true, detail: "Found" });
+    } catch {
+      checks.push({ name: ".env", ok: false, detail: "Not found" });
+    }
+
+    // 4. Check global config
+    {
+      let hasGlobal = false;
+      try {
+        const globalContent = await readFile(GLOBAL_ENV_PATH, "utf-8");
+        hasGlobal = globalContent.includes("INKOS_LLM_API_KEY=") && !globalContent.includes("your-api-key-here");
+      } catch { /* no global config */ }
+      checks.push({
+        name: "Global Config",
+        ok: hasGlobal,
+        detail: hasGlobal ? `Found (${GLOBAL_ENV_PATH})` : "Not set. Run 'inkos config set-global'",
+      });
+    }
+
+    // 5. Check effective LLM config (Studio project base + env/CLI overlay, or legacy env)
+    {
+      const { loadConfigWithDiagnostics } = await import("../utils.js");
+      const { isApiKeyOptionalForEndpoint } = await import("@actalk/inkos-core");
+      let configResult: Awaited<ReturnType<typeof loadConfigWithDiagnostics>> | undefined;
+      try {
+        configResult = await loadConfigWithDiagnostics({ requireApiKey: false });
+        checks.push({
+          name: "LLM Config Mode",
+          ok: true,
+          detail: `${configResult.diagnostics.configMode} (service=${configResult.diagnostics.serviceSource}, model=${configResult.diagnostics.modelSource}, key=${configResult.diagnostics.apiKeySource})`,
+        });
+        for (const warning of configResult.diagnostics.warnings) {
+          checks.push({ name: "  Config Hint", ok: true, detail: warning });
+        }
+      } catch {
+        // The API connectivity check below will report the concrete config failure.
+      }
+      const provider = configResult?.llm.provider;
+      const baseUrl = configResult?.llm.baseUrl;
+      const apiKey = configResult?.llm.apiKey;
+      const apiKeyOptional = isApiKeyOptionalForEndpoint({ provider, baseUrl });
+      const hasKey = apiKeyOptional || (!!apiKey && apiKey.length > 10 && apiKey !== "your-api-key-here");
+      checks.push({
+        name: "LLM API Key",
+        ok: hasKey,
+        detail: apiKeyOptional
+          ? "Optional for local/self-hosted endpoint"
+          : hasKey
+            ? "Configured"
+            : "Missing — save a Studio service key or set env for CLI/daemon/deploy",
+      });
+    }
+
+    // 5. Check books directory
+    try {
+      const { StateManager } = await import("@actalk/inkos-core");
+      const state = new StateManager(root);
+      const books = await state.listBooks();
+      checks.push({
+        name: "Books",
+        ok: true,
+        detail: `${books.length} book(s) found`,
+      });
+    } catch {
+      checks.push({ name: "Books", ok: true, detail: "0 books" });
+    }
+
+    // 5b. Check version migration status
+    {
+      const { existsSync } = await import("node:fs");
+      const hasStructuredState = existsSync(join(root, "books"));
+      if (hasStructuredState) {
+        const { StateManager } = await import("@actalk/inkos-core");
+        const sm = new StateManager(root);
+        const bookIds = await sm.listBooks();
+        let legacyCount = 0;
+        for (const bid of bookIds) {
+          const stateDir = join(sm.bookDir(bid), "story", "state");
+          const hasNewState = existsSync(stateDir);
+          if (!hasNewState) legacyCount++;
+        }
+        if (legacyCount > 0) {
+          checks.push({
+            name: "Version Migration",
+            ok: false,
+            detail: `${legacyCount} book(s) using legacy format (pre-v0.6). Run 'inkos write next' on each to auto-migrate, or re-init with 'inkos init'.`,
+          });
+        } else if (bookIds.length > 0) {
+          checks.push({
+            name: "Version Migration",
+            ok: true,
+            detail: "All books use current format",
+          });
+        }
+      }
+    }
+
+    // 6. API connectivity test
+    try {
+      const { createLLMClient, chatCompletion, LLMConfigSchema, isApiKeyOptionalForEndpoint, resolveServiceModelsBaseUrl } = await import("@actalk/inkos-core");
+      const { loadConfig } = await import("../utils.js");
+
+      let llmConfig;
+      try {
+        const config = await loadConfig();
+        llmConfig = config.llm;
+      } catch {
+        // No project config — try building from global env
+        const { config: loadDotenv } = await import("dotenv");
+        loadDotenv({ path: GLOBAL_ENV_PATH });
+        const env = process.env;
+        const apiKeyOptional = isApiKeyOptionalForEndpoint({
+          provider: env.INKOS_LLM_PROVIDER,
+          baseUrl: env.INKOS_LLM_BASE_URL,
+        });
+        if ((env.INKOS_LLM_API_KEY || apiKeyOptional) && env.INKOS_LLM_BASE_URL && env.INKOS_LLM_MODEL) {
+          llmConfig = LLMConfigSchema.parse({
+            provider: env.INKOS_LLM_PROVIDER ?? "custom",
+            baseUrl: env.INKOS_LLM_BASE_URL,
+            apiKey: env.INKOS_LLM_API_KEY ?? "",
+            model: env.INKOS_LLM_MODEL,
+          });
+        }
+      }
+
+      if (!llmConfig) {
+        checks.push({
+          name: "API Connectivity",
+          ok: false,
+          detail: "No LLM config available (no project config or global .env)",
+        });
+        checks.push({
+          name: "  Hint",
+          ok: false,
+          detail: "Run `inkos setup`, `inkos config set-global`, or add LLM settings to the project .env file.",
+        });
+      } else {
+        checks.push({
+          name: "LLM Config",
+          ok: true,
+          detail: `provider=${llmConfig.provider} model=${llmConfig.model} stream=${llmConfig.stream ?? true} baseUrl=${llmConfig.baseUrl}`,
+        });
+
+        log("\n  [..] Testing API connectivity...");
+
+        let connected = false;
+        let detectedDetail = "";
+        let lastError = "Unknown error";
+        const modelsBaseUrl = resolveDoctorModelsBaseUrl(
+          typeof llmConfig.service === "string" ? llmConfig.service : undefined,
+          llmConfig.baseUrl,
+          resolveServiceModelsBaseUrl,
+        );
+        const discoveredModels = (llmConfig.apiKey && modelsBaseUrl)
+          ? await fetchDoctorModels(modelsBaseUrl, llmConfig.apiKey, llmConfig.proxyUrl)
+          : [];
+        const modelCandidates = (llmConfig.provider === "openai" || discoveredModels.length > 0)
+          ? buildDoctorModelCandidates(llmConfig.model, discoveredModels)
+          : [llmConfig.model];
+        const plans = llmConfig.provider === "openai"
+          ? buildDoctorProbePlans(llmConfig.apiFormat, llmConfig.stream)
+          : [{ apiFormat: (llmConfig.apiFormat ?? "chat") as "chat" | "responses", stream: llmConfig.stream ?? true }];
+
+        for (const model of modelCandidates) {
+          for (const plan of plans) {
+            try {
+              const client = createLLMClient({
+                ...llmConfig,
+                model,
+                apiFormat: plan.apiFormat,
+                stream: plan.stream,
+              });
+              const response = await chatCompletion(client, model, [
+                { role: "user", content: "Say OK" },
+              ], { maxTokens: 16 });
+
+              connected = true;
+              detectedDetail = `OK (model: ${model}, apiFormat=${plan.apiFormat}, stream=${plan.stream}, tokens: ${response.usage.totalTokens})`;
+              break;
+            } catch (error) {
+              lastError = error instanceof Error ? error.message : String(error);
+            }
+          }
+          if (connected) {
+            break;
+          }
+        }
+
+        checks.push({
+          name: "API Connectivity",
+          ok: connected,
+          detail: connected ? detectedDetail : lastError.split("\n")[0]!,
+        });
+
+        if (!connected && /\b(?:401|403|429)\b|unauthorized|forbidden|quota|额度|余额|配额/i.test(lastError)) {
+          checks.push({
+            name: "  Hint",
+            ok: false,
+            detail: "检查 API Key 是否正确、模型是否可用，以及账号余额或配额是否足够。",
+          });
+        }
+
+        if (!connected && llmConfig.provider === "openai") {
+          checks.push({
+            name: "  Hint",
+            ok: false,
+            detail: "当前已自动尝试 chat/responses 与流式开关组合；如果仍失败，问题更可能在模型名、baseUrl 路径或服务商兼容性本身。",
+          });
+        }
+      }
+    } catch (e) {
+      const errMsg = String(e);
+      const hints: string[] = [];
+
+      if (errMsg.includes("Connection error") || errMsg.includes("ECONNREFUSED") || errMsg.includes("fetch failed")) {
+        hints.push("baseUrl 可能不正确，检查 INKOS_LLM_BASE_URL 是否包含完整路径（如 /v1）");
+      }
+      if (errMsg.includes("400")) {
+        hints.push("检查提供方文档，确认该接口要求 stream=true、stream=false，还是根本不支持 stream");
+        hints.push("检查模型名称是否正确（INKOS_LLM_MODEL）");
+      }
+      if (errMsg.includes("401")) {
+        hints.push("API Key 无效，检查 INKOS_LLM_API_KEY");
+      }
+
+      checks.push({
+        name: "API Connectivity",
+        ok: false,
+        detail: errMsg.split("\n")[0]!,
+      });
+
+      if (hints.length > 0) {
+        for (const hint of hints) {
+          checks.push({ name: "  Hint", ok: false, detail: hint });
+        }
+      }
+    }
+
+    // Output
+    log("\nInkOS Doctor\n");
+    for (const check of checks) {
+      const icon = check.ok ? "[OK]" : "[!!]";
+      log(`  ${icon} ${check.name}: ${check.detail}`);
+    }
+
+    const failed = checks.filter((c) => !c.ok);
+    if (failed.length > 0) {
+      log(`\n${failed.length} issue(s) found.`);
+    } else {
+      log("\nAll checks passed.");
+    }
+  });

package/inkos/packages/cli/src/commands/draft.ts

@@ -0,0 +1,43 @@
+import { Command } from "commander";
+import { PipelineRunner } from "@actalk/inkos-core";
+import { loadConfig, buildPipelineConfig, findProjectRoot, resolveContext, resolveBookId, log, logError } from "../utils.js";
+
+export const draftCommand = new Command("draft")
+  .description("Write a draft chapter (no audit/revise)")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .option("--words <n>", "Words per chapter (overrides book config)")
+  .option("--context <text>", "Creative guidance (natural language)")
+  .option("--context-file <path>", "Read guidance from file")
+  .option("--json", "Output JSON")
+  .option("-q, --quiet", "Suppress console output")
+  .action(async (bookIdArg: string | undefined, opts) => {
+    try {
+      const config = await loadConfig();
+      const root = findProjectRoot();
+      const bookId = await resolveBookId(bookIdArg, root);
+      const context = await resolveContext(opts);
+
+      const pipeline = new PipelineRunner(buildPipelineConfig(config, root, { quiet: opts.quiet }));
+
+      const wordCount = opts.words ? parseInt(opts.words, 10) : undefined;
+
+      if (!opts.json) log(`Writing draft for "${bookId}"...`);
+
+      const result = await pipeline.writeDraft(bookId, context, wordCount);
+
+      if (opts.json) {
+        log(JSON.stringify(result, null, 2));
+      } else {
+        log(`  Chapter ${result.chapterNumber}: ${result.title}`);
+        log(`  Words: ${result.wordCount}`);
+        log(`  File: ${result.filePath}`);
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to write draft: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

package/inkos/packages/cli/src/commands/eval.ts

@@ -0,0 +1,217 @@
+import { Command } from "commander";
+import {
+  StateManager,
+  analyzeAITells,
+  computeAnalytics,
+} from "@actalk/inkos-core";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { findProjectRoot, resolveBookId, log, logError } from "../utils.js";
+
+interface ChapterEval {
+  readonly number: number;
+  readonly title: string;
+  readonly wordCount: number;
+  readonly auditIssueCount: number;
+  readonly aiTellCount: number;
+  readonly aiTellDensity: number; // issues per 1000 chars
+  readonly paragraphWarnings: number;
+  readonly status: string;
+}
+
+interface BookEval {
+  readonly bookId: string;
+  readonly totalChapters: number;
+  readonly totalWords: number;
+  readonly auditPassRate: number;
+  readonly avgAiTellDensity: number;
+  readonly avgParagraphWarnings: number;
+  readonly hookResolveRate: number;
+  readonly duplicateTitles: number;
+  readonly qualityScore: number; // composite 0-100
+  readonly chapters: ReadonlyArray<ChapterEval>;
+  readonly qualityTrend: ReadonlyArray<{ chapter: number; score: number }>;
+}
+
+function computeChapterScore(ch: ChapterEval): number {
+  // Per-chapter quality score (0-100)
+  // Penalties: audit issues, AI tells, paragraph problems
+  let score = 100;
+  score -= ch.auditIssueCount * 5; // -5 per audit issue
+  score -= ch.aiTellDensity * 20;  // -20 per AI tell per 1k chars
+  score -= ch.paragraphWarnings * 3; // -3 per paragraph warning
+  return Math.max(0, Math.min(100, score));
+}
+
+export const evalCommand = new Command("eval")
+  .description("Evaluate writing quality for a book — outputs structured quality report")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .option("--json", "Output JSON only")
+  .option("--chapters <range>", "Chapter range (e.g. 1-10, 5-20)")
+  .action(async (bookIdArg: string | undefined, opts: { json?: boolean; chapters?: string }) => {
+    try {
+      const root = findProjectRoot();
+      const bookId = await resolveBookId(bookIdArg, root);
+      const state = new StateManager(root);
+      const index = await state.loadChapterIndex(bookId);
+      const bookDir = state.bookDir(bookId);
+      const chaptersDir = join(bookDir, "chapters");
+
+      // Parse chapter range
+      let startCh = 1;
+      let endCh = Infinity;
+      if (opts.chapters) {
+        const parts = opts.chapters.split("-");
+        startCh = parseInt(parts[0]!, 10);
+        endCh = parts[1] ? parseInt(parts[1], 10) : startCh;
+      }
+
+      const filteredIndex = index.filter(
+        (ch) => ch.number >= startCh && ch.number <= endCh,
+      );
+
+      // Read chapter files and evaluate each
+      const chapterFiles = await readdir(chaptersDir).catch(() => [] as string[]);
+      const allTitles = index.map((ch) => ch.title);
+      const chapterEvals: ChapterEval[] = [];
+
+      for (const ch of filteredIndex) {
+        const paddedNum = String(ch.number).padStart(4, "0");
+        const file = chapterFiles.find(
+          (f) => f.startsWith(paddedNum) && f.endsWith(".md"),
+        );
+        let content = "";
+        if (file) {
+          content = await readFile(join(chaptersDir, file), "utf-8");
+        }
+
+        const aiTells = content ? analyzeAITells(content) : { issues: [] };
+        // Simple paragraph shape check: count short paragraphs
+        const paragraphs = content.split(/\n\s*\n/).map((p) => p.trim()).filter((p) => p.length > 0 && !p.startsWith("#"));
+        const shortParas = paragraphs.filter((p) => p.length < 35);
+        const paragraphWarningCount = shortParas.length > paragraphs.length * 0.4 ? 1 : 0;
+
+        const aiTellDensity = content.length > 0
+          ? (aiTells.issues.length / content.length) * 1000
+          : 0;
+
+        chapterEvals.push({
+          number: ch.number,
+          title: ch.title,
+          wordCount: ch.wordCount,
+          auditIssueCount: ch.auditIssues.length,
+          aiTellCount: aiTells.issues.length,
+          aiTellDensity: Math.round(aiTellDensity * 100) / 100,
+          paragraphWarnings: paragraphWarningCount,
+          status: ch.status,
+        });
+      }
+
+      // Hook health: parse markdown for status counts
+      const hooksContent = await readFile(
+        join(bookDir, "story", "pending_hooks.md"),
+        "utf-8",
+      ).catch(() => "");
+      let hookResolveRate = 0;
+      if (hooksContent) {
+        const lines = hooksContent.split("\n");
+        let totalHooks = 0;
+        let resolvedHooks = 0;
+        for (const line of lines) {
+          if (/^\|.*\|.*\|/.test(line) && !line.includes("---") && !line.toLowerCase().includes("hook") && !line.toLowerCase().includes("伏笔")) {
+            totalHooks++;
+            if (/resolved|已回收|已解决/i.test(line)) resolvedHooks++;
+          }
+        }
+        hookResolveRate = totalHooks > 0
+          ? Math.round((resolvedHooks / totalHooks) * 100)
+          : 0;
+      }
+
+      // Duplicate titles: simple exact match
+      const titleSet = new Set<string>();
+      let duplicateTitles = 0;
+      for (const title of allTitles) {
+        const norm = title.trim().toLowerCase();
+        if (titleSet.has(norm)) duplicateTitles++;
+        titleSet.add(norm);
+      }
+
+      // Composite score
+      const analytics = computeAnalytics(bookId, index);
+      const avgAiTellDensity = chapterEvals.length > 0
+        ? chapterEvals.reduce((s, c) => s + c.aiTellDensity, 0) / chapterEvals.length
+        : 0;
+      const avgParagraphWarnings = chapterEvals.length > 0
+        ? chapterEvals.reduce((s, c) => s + c.paragraphWarnings, 0) / chapterEvals.length
+        : 0;
+
+      // Quality score: weighted composite (0-100)
+      const qualityScore = Math.round(
+        analytics.auditPassRate * 0.3 +                        // 30% audit
+        Math.max(0, 100 - avgAiTellDensity * 30) * 0.25 +     // 25% AI tells
+        Math.max(0, 100 - avgParagraphWarnings * 10) * 0.15 +  // 15% paragraphs
+        hookResolveRate * 0.2 +                                 // 20% hooks
+        Math.max(0, 100 - duplicateTitles * 20) * 0.1,         // 10% title dedup
+      );
+
+      // Quality trend (per-chapter scores)
+      const qualityTrend = chapterEvals.map((ch) => ({
+        chapter: ch.number,
+        score: computeChapterScore(ch),
+      }));
+
+      const result: BookEval = {
+        bookId,
+        totalChapters: filteredIndex.length,
+        totalWords: filteredIndex.reduce((s, c) => s + c.wordCount, 0),
+        auditPassRate: analytics.auditPassRate,
+        avgAiTellDensity: Math.round(avgAiTellDensity * 100) / 100,
+        avgParagraphWarnings: Math.round(avgParagraphWarnings * 100) / 100,
+        hookResolveRate,
+        duplicateTitles,
+        qualityScore,
+        chapters: chapterEvals,
+        qualityTrend,
+      };
+
+      if (opts.json) {
+        log(JSON.stringify(result, null, 2));
+      } else {
+        log(`\nQuality Report: "${bookId}"\n`);
+        log(`  Quality Score: ${qualityScore}/100`);
+        log(`  Chapters: ${result.totalChapters}`);
+        log(`  Words: ${result.totalWords.toLocaleString()}`);
+        log("");
+        log("  Dimensions:");
+        log(`    Audit pass rate:      ${analytics.auditPassRate}%`);
+        log(`    AI tell density:      ${avgAiTellDensity.toFixed(2)} / 1k chars`);
+        log(`    Paragraph warnings:   ${avgParagraphWarnings.toFixed(1)} avg/chapter`);
+        log(`    Hook resolve rate:    ${hookResolveRate}%`);
+        log(`    Duplicate titles:     ${duplicateTitles}`);
+        log("");
+        log("  Quality Trend:");
+        for (const { chapter, score } of qualityTrend) {
+          const bar = "█".repeat(Math.round(score / 5)) + "░".repeat(20 - Math.round(score / 5));
+          log(`    Ch.${String(chapter).padStart(3)} ${bar} ${score}`);
+        }
+        log("");
+
+        // Drift detection: compare first half vs second half
+        if (qualityTrend.length >= 6) {
+          const mid = Math.floor(qualityTrend.length / 2);
+          const firstHalf = qualityTrend.slice(0, mid).reduce((s, c) => s + c.score, 0) / mid;
+          const secondHalf = qualityTrend.slice(mid).reduce((s, c) => s + c.score, 0) / (qualityTrend.length - mid);
+          const drift = Math.round(secondHalf - firstHalf);
+          log(`  Quality Drift: ${drift > 0 ? "+" : ""}${drift} (${drift >= 0 ? "stable/improving" : "DEGRADING"})`);
+        }
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Eval failed: ${e}`);
+      }
+      process.exit(1);
+    }
+  });

package/inkos/packages/cli/src/commands/export.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { StateManager, writeExportArtifact } from "@actalk/inkos-core";
+import { join } from "node:path";
+import { findProjectRoot, resolveBookId, log, logError } from "../utils.js";
+
+export const exportCommand = new Command("export")
+  .description("Export book chapters to a single file")
+  .argument("[book-id]", "Book ID (auto-detected if only one book)")
+  .option("--format <format>", "Output format (txt, md, epub)", "txt")
+  .option("--output <path>", "Output file path")
+  .option("--approved-only", "Only export approved chapters")
+  .option("--json", "Output JSON metadata")
+  .action(async (bookIdArg: string | undefined, opts) => {
+    try {
+      const root = findProjectRoot();
+      const bookId = await resolveBookId(bookIdArg, root);
+      const state = new StateManager(root);
+
+      const result = await writeExportArtifact(state, bookId, {
+        format: opts.format as "txt" | "md" | "epub",
+        approvedOnly: Boolean(opts.approvedOnly),
+        outputPath: opts.output ?? join(root, `${bookId}_export.${opts.format}`),
+      });
+
+      if (opts.json) {
+        log(JSON.stringify({
+          bookId,
+          chaptersExported: result.chaptersExported,
+          totalWords: result.totalWords,
+          format: result.format,
+          outputPath: result.outputPath,
+        }, null, 2));
+      } else {
+        log(`Exported ${result.chaptersExported} chapters (${result.totalWords} words)`);
+        log(`Output: ${result.outputPath}`);
+      }
+    } catch (e) {
+      if (opts.json) {
+        log(JSON.stringify({ error: String(e) }));
+      } else {
+        logError(`Failed to export: ${e}`);
+      }
+      process.exit(1);
+    }
+  });