novelforge-agent 0.1.0 → 0.2.0

package/src/cli/install.ts

@@ -0,0 +1,275 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export type InstallHost = 'claude-code' | 'codex' | 'cursor';
+
+export interface InstallOptions {
+  host?: InstallHost;
+  workspace?: string;
+  name?: string;
+  printOnly?: boolean;
+}
+
+export interface InstallResult {
+  host: InstallHost;
+  name: string;
+  workspace: string;
+  applied: boolean;
+  method: 'cli' | 'config-edit' | 'print-only';
+  message: string;
+  manualSnippet?: string;
+  verificationHint: string;
+}
+
+const PACKAGE_NAME = 'novelforge-agent';
+const MCP_BIN = 'novelforge-agent-mcp';
+
+function defaultWorkspace(): string {
+  return join(homedir(), 'novelforge');
+}
+
+function defaultName(): string {
+  return 'novelforge';
+}
+
+function claudeJsonSnippet(name: string, workspace: string): string {
+  return JSON.stringify(
+    {
+      mcpServers: {
+        [name]: {
+          command: 'npx',
+          args: ['-y', MCP_BIN],
+          env: { NOVELFORGE_WORKSPACE: workspace },
+        },
+      },
+    },
+    null,
+    2
+  );
+}
+
+function codexTomlSnippet(name: string, workspace: string): string {
+  return [
+    `[mcp_servers.${name}]`,
+    `command = "npx"`,
+    `args = ["-y", "${MCP_BIN}"]`,
+    ``,
+    `[mcp_servers.${name}.env]`,
+    `NOVELFORGE_WORKSPACE = "${workspace}"`,
+    ``,
+  ].join('\n');
+}
+
+function cursorSnippet(name: string, workspace: string): string {
+  return JSON.stringify(
+    {
+      mcpServers: {
+        [name]: {
+          command: 'npx',
+          args: ['-y', MCP_BIN],
+          env: { NOVELFORGE_WORKSPACE: workspace },
+        },
+      },
+    },
+    null,
+    2
+  );
+}
+
+async function ensureWorkspaceDir(workspace: string): Promise<void> {
+  await mkdir(workspace, { recursive: true });
+  await mkdir(join(workspace, 'novels'), { recursive: true });
+}
+
+async function tryClaudeCli(name: string, workspace: string): Promise<{ ok: boolean; output: string; error?: string }> {
+  const args = [
+    'mcp',
+    'add',
+    '-s',
+    'user',
+    '-e',
+    `NOVELFORGE_WORKSPACE=${workspace}`,
+    name,
+    '--',
+    'npx',
+    '-y',
+    MCP_BIN,
+  ];
+  try {
+    const { stdout, stderr } = await execFileAsync('claude', args);
+    return { ok: true, output: `${stdout}\n${stderr}`.trim() };
+  } catch (error) {
+    const err = error as Error & { code?: string };
+    return { ok: false, output: '', error: err.message };
+  }
+}
+
+async function applyClaudeCode(name: string, workspace: string, printOnly: boolean): Promise<InstallResult> {
+  const snippet = claudeJsonSnippet(name, workspace);
+  const verificationHint =
+    'In Claude Code, ask the assistant: "list_projects 现在能用吗?". The host should call the list_projects tool and return an empty array.';
+
+  if (printOnly) {
+    return {
+      host: 'claude-code',
+      name,
+      workspace,
+      applied: false,
+      method: 'print-only',
+      message:
+        'Print-only mode. Run the snippet below or invoke without --print-only to apply automatically.',
+      manualSnippet: snippet,
+      verificationHint,
+    };
+  }
+
+  const cli = await tryClaudeCli(name, workspace);
+  if (cli.ok) {
+    return {
+      host: 'claude-code',
+      name,
+      workspace,
+      applied: true,
+      method: 'cli',
+      message: `Registered via \`claude mcp add\`.\n${cli.output}`,
+      verificationHint,
+    };
+  }
+  return {
+    host: 'claude-code',
+    name,
+    workspace,
+    applied: false,
+    method: 'print-only',
+    message:
+      `\`claude\` CLI not available (${cli.error ?? 'unknown error'}). Paste the snippet below into ~/.claude.json under "mcpServers", or run \`claude mcp add -s user -e NOVELFORGE_WORKSPACE=${workspace} ${name} -- npx -y ${MCP_BIN}\` after installing Claude Code.`,
+    manualSnippet: snippet,
+    verificationHint,
+  };
+}
+
+async function applyCodex(name: string, workspace: string, printOnly: boolean): Promise<InstallResult> {
+  const snippet = codexTomlSnippet(name, workspace);
+  const configPath = join(homedir(), '.codex', 'config.toml');
+  const verificationHint =
+    'In Codex CLI, ask the assistant: "list_projects 现在能用吗?". The host should call the list_projects tool and return an empty array.';
+
+  if (printOnly) {
+    return {
+      host: 'codex',
+      name,
+      workspace,
+      applied: false,
+      method: 'print-only',
+      message: `Print-only mode. Append the snippet below to ${configPath}.`,
+      manualSnippet: snippet,
+      verificationHint,
+    };
+  }
+
+  try {
+    await mkdir(dirname(configPath), { recursive: true });
+    let existing = '';
+    try {
+      existing = await readFile(configPath, 'utf8');
+    } catch {
+      existing = '';
+    }
+    if (existing.includes(`[mcp_servers.${name}]`)) {
+      return {
+        host: 'codex',
+        name,
+        workspace,
+        applied: false,
+        method: 'config-edit',
+        message: `Section [mcp_servers.${name}] already exists in ${configPath}. Edit it manually if you want to change settings.`,
+        manualSnippet: snippet,
+        verificationHint,
+      };
+    }
+    const next = existing.endsWith('\n') || existing === '' ? existing : `${existing}\n`;
+    await writeFile(configPath, `${next}\n${snippet}`, 'utf8');
+    return {
+      host: 'codex',
+      name,
+      workspace,
+      applied: true,
+      method: 'config-edit',
+      message: `Appended [mcp_servers.${name}] to ${configPath}.`,
+      verificationHint,
+    };
+  } catch (error) {
+    return {
+      host: 'codex',
+      name,
+      workspace,
+      applied: false,
+      method: 'print-only',
+      message: `Could not write ${configPath}: ${(error as Error).message}. Append the snippet manually.`,
+      manualSnippet: snippet,
+      verificationHint,
+    };
+  }
+}
+
+async function applyCursor(name: string, workspace: string, printOnly: boolean): Promise<InstallResult> {
+  const snippet = cursorSnippet(name, workspace);
+  return {
+    host: 'cursor',
+    name,
+    workspace,
+    applied: false,
+    method: 'print-only',
+    message:
+      'Cursor: open Settings → Tools & Integrations → MCP, click "Add new MCP server", and paste the snippet below.',
+    manualSnippet: snippet,
+    verificationHint:
+      'In Cursor, the agent should be able to call the list_projects tool from the novelforge MCP server.',
+  };
+}
+
+export async function runInstall(options: InstallOptions): Promise<InstallResult> {
+  const host: InstallHost = options.host ?? 'claude-code';
+  const workspace = resolve(options.workspace ?? defaultWorkspace());
+  const name = options.name ?? defaultName();
+  const printOnly = options.printOnly ?? false;
+
+  if (!printOnly) {
+    await ensureWorkspaceDir(workspace);
+  }
+
+  switch (host) {
+    case 'claude-code':
+      return applyClaudeCode(name, workspace, printOnly);
+    case 'codex':
+      return applyCodex(name, workspace, printOnly);
+    case 'cursor':
+      return applyCursor(name, workspace, printOnly);
+    default:
+      throw new Error(`Unknown host: ${host}. Use claude-code | codex | cursor.`);
+  }
+}
+
+export function formatInstallResult(result: InstallResult): string {
+  const parts: string[] = [];
+  parts.push(`Host:        ${result.host}`);
+  parts.push(`MCP name:    ${result.name}`);
+  parts.push(`Workspace:   ${result.workspace}`);
+  parts.push(`Applied:     ${result.applied ? 'yes' : 'no'} (${result.method})`);
+  parts.push('');
+  parts.push(result.message);
+  if (result.manualSnippet) {
+    parts.push('');
+    parts.push('--- Snippet ---');
+    parts.push(result.manualSnippet);
+    parts.push('---------------');
+  }
+  parts.push('');
+  parts.push(`Verify: ${result.verificationHint}`);
+  return parts.join('\n');
+}

package/src/core/bibleStore.ts

@@ -0,0 +1,57 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  archiveStoryBible,
+  loadState,
+  saveMarkdownFile,
+  saveState,
+} from './projectStore.js';
+import { storyBibleVersionFileName } from './fileNames.js';
+import { indexStoryBible } from './retrieval/index.js';
+
+export interface AmendStoryBibleInput {
+  projectPath: string;
+  content: string;
+  reason?: string;
+}
+
+export interface AmendStoryBibleResult {
+  archivedPath?: string;
+  bibleVersion: number;
+  savedPath: string;
+}
+
+function isEmpty(content: string): boolean {
+  return !content || !content.trim();
+}
+
+export async function amendStoryBible(input: AmendStoryBibleInput): Promise<AmendStoryBibleResult> {
+  if (isEmpty(input.content)) throw new Error('Amended story bible content is empty');
+  const state = await loadState(input.projectPath);
+  // Archive current
+  const archived = await archiveStoryBible(
+    state.projectPath,
+    join('story-bible-versions', storyBibleVersionFileName(new Date().toISOString()))
+  );
+  // Save new
+  const savedPath = await saveMarkdownFile(state.projectPath, 'story-bible.md', input.content);
+  // Re-index
+  await indexStoryBible(state.projectPath, input.content);
+  // Track in state
+  const bibleVersion = (state.completedSteps.filter((s) => s === 'story_bible_amend').length ?? 0) + 1;
+  await saveState({
+    ...state,
+    completedSteps: [...state.completedSteps, 'story_bible_amend' as const],
+    files: { ...state.files, storyBible: 'story-bible.md' },
+  });
+  return { archivedPath: archived, bibleVersion, savedPath };
+}
+
+export async function listStoryBibleVersions(projectPath: string): Promise<string[]> {
+  try {
+    const items = await readdir(join(projectPath, 'story-bible-versions'));
+    return items.filter((f) => f.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+}

package/src/core/characterStore.ts

@@ -0,0 +1,93 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CharacterState, CharacterStateUpdate, CoreCastMember } from './types.js';
+
+const CHARACTERS_FILE = 'characters.json';
+
+export interface CharactersBundle {
+  characters: CharacterState[];
+}
+
+function emptyState(member: CoreCastMember, chapterNumber = 0): CharacterState {
+  return {
+    name: member.name,
+    role: member.role,
+    goal: '未确认',
+    belief: '未确认',
+    relationships: [],
+    abilities: [],
+    secrets: [],
+    emotionalState: member.description,
+    lastUpdatedAt: chapterNumber,
+  };
+}
+
+export async function loadCharacterStates(projectPath: string): Promise<CharacterState[]> {
+  try {
+    const raw = await readFile(join(projectPath, CHARACTERS_FILE), 'utf8');
+    const parsed = JSON.parse(raw) as CharactersBundle;
+    return Array.isArray(parsed.characters) ? parsed.characters : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function saveCharacterStates(projectPath: string, characters: CharacterState[]): Promise<string> {
+  const fullPath = join(projectPath, CHARACTERS_FILE);
+  await writeFile(fullPath, `${JSON.stringify({ characters }, null, 2)}\n`, 'utf8');
+  return fullPath;
+}
+
+export async function initializeCharacterStates(
+  projectPath: string,
+  coreCast: CoreCastMember[]
+): Promise<string> {
+  const existing = await loadCharacterStates(projectPath);
+  const byName = new Map(existing.map((c) => [c.name, c]));
+  for (const member of coreCast) {
+    if (!byName.has(member.name)) {
+      byName.set(member.name, emptyState(member));
+    }
+  }
+  return saveCharacterStates(projectPath, Array.from(byName.values()));
+}
+
+export async function applyCharacterUpdates(
+  projectPath: string,
+  chapterNumber: number,
+  updates: CharacterStateUpdate[] | undefined
+): Promise<CharacterState[]> {
+  const existing = await loadCharacterStates(projectPath);
+  if (!updates || !updates.length) return existing;
+
+  const byName = new Map(existing.map((c) => [c.name, { ...c }]));
+  for (const update of updates) {
+    const current = byName.get(update.name) ?? {
+      name: update.name,
+      role: update.role,
+      goal: '未确认',
+      belief: '未确认',
+      relationships: [],
+      abilities: [],
+      secrets: [],
+      emotionalState: '未确认',
+      lastUpdatedAt: chapterNumber,
+    };
+
+    byName.set(update.name, {
+      ...current,
+      role: update.role ?? current.role,
+      goal: update.goal ?? current.goal,
+      belief: update.belief ?? current.belief,
+      relationships: update.relationships ?? current.relationships,
+      abilities: update.abilities ?? current.abilities,
+      secrets: update.secrets ?? current.secrets,
+      emotionalState: update.emotionalState ?? current.emotionalState,
+      lastUpdatedAt: chapterNumber,
+    });
+  }
+
+  const next = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+  await saveCharacterStates(projectPath, next);
+  return next;
+}

package/src/core/contextBuilder.ts

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { chapterFileName, chapterReviewFileName, memoryFileName } from './fileNames.js';
 import { formatHits, retrieve } from './retrieval/index.js';
+import { activeThreads, loadThreads } from './threadStore.js';
 
 export type ContextPurpose =
   | 'chapter_generation'
@@ -32,18 +33,33 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
   const metadata = await readOptional(join(input.projectPath, 'novel.json'));
   const storyBible = await readOptional(join(input.projectPath, 'story-bible.md'));
   const chaptersJson = await readOptional(join(input.projectPath, 'architecture/chapters.json'));
+  const charactersJson = await readOptional(join(input.projectPath, 'characters.json'));
+  const volumePacingJson = await readOptional(join(input.projectPath, 'architecture/volume-pacing.json'));
 
   if (metadata) parts.push(`## Novel Metadata\n${metadata}`);
   if (storyBible) parts.push(`## Story Bible\n${storyBible.slice(0, 4000)}`);
+  if (charactersJson) parts.push(`## Character State Table\n${charactersJson}`);
+
+  function addVolumePacing(volumeId?: string): void {
+    if (!volumePacingJson) return;
+    try {
+      const boards = JSON.parse(volumePacingJson) as Array<{ volumeId: string }>;
+      const board = volumeId ? boards.find((item) => item.volumeId === volumeId) : undefined;
+      parts.push(`## Volume Pacing Board\n${JSON.stringify(board ?? boards, null, 2)}`);
+    } catch {
+      parts.push(`## Volume Pacing Board\n${volumePacingJson}`);
+    }
+  }
 
   if (input.purpose === 'chapter_generation' && input.chapterNumber) {
-    let currentArchitectureForQuery: { summary?: string; requiredBeats?: string[]; title?: string } | undefined;
+    let currentArchitectureForQuery: { summary?: string; requiredBeats?: string[]; title?: string; volumeId?: string } | undefined;
     if (chaptersJson) {
-      const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[] }>;
+      const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[]; volumeId?: string }>;
       const chapter = chapters.find((item) => item.chapterNumber === input.chapterNumber);
       if (chapter) {
         currentArchitectureForQuery = chapter;
         parts.push(`## Current Chapter Architecture\n${JSON.stringify(chapter, null, 2)}`);
+        addVolumePacing(chapter.volumeId);
       }
     }
     if (input.chapterNumber > 1) {
@@ -67,6 +83,18 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
         const formatted = formatHits(hits);
         if (formatted) parts.push(`## Retrieved Relevant Snippets (lexical, BM25-style)\n${formatted}`);
       }
+
+      const allThreads = await loadThreads(input.projectPath);
+      const active = activeThreads(allThreads);
+      if (active.length) {
+        const lines = active.map((t) => {
+          const flags: string[] = [`#${t.id}`, `status=${t.status}`, `planted=ch${t.plantedAt}`];
+          if (t.plannedPayoffAt) flags.push(`payoff=ch${t.plannedPayoffAt}`);
+          if (t.lastTouchedAt !== t.plantedAt) flags.push(`touched=ch${t.lastTouchedAt}`);
+          return `- ${t.description}  (${flags.join(', ')})`;
+        });
+        parts.push(`## Active Foreshadow Threads (do not silently drop or contradict)\n${lines.join('\n')}`);
+      }
     }
   }
 
@@ -87,9 +115,12 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
 
   if (input.purpose === 'chapter_review' && input.chapterNumber) {
     if (chaptersJson) {
-      const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[] }>;
+      const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; title: string; summary: string; requiredBeats?: string[]; volumeId?: string }>;
       const arch = chapters.find((item) => item.chapterNumber === input.chapterNumber);
-      if (arch) parts.push(`## Target Chapter Architecture\n${JSON.stringify(arch, null, 2)}`);
+      if (arch) {
+        parts.push(`## Target Chapter Architecture\n${JSON.stringify(arch, null, 2)}`);
+        addVolumePacing(arch.volumeId);
+      }
     }
     const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
     if (chapter) parts.push(`## Chapter ${input.chapterNumber} Text\n${chapter}`);
@@ -102,6 +133,15 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
   if (input.purpose === 'revision' && input.chapterNumber) {
     const chapter = await readOptional(join(input.projectPath, 'chapters', chapterFileName(input.chapterNumber)));
     if (chapter) parts.push(`## Current Chapter Text\n${chapter}`);
+    if (chaptersJson) {
+      try {
+        const chapters = JSON.parse(chaptersJson) as Array<{ chapterNumber: number; volumeId?: string }>;
+        const arch = chapters.find((item) => item.chapterNumber === input.chapterNumber);
+        addVolumePacing(arch?.volumeId);
+      } catch {
+        // ignore malformed architecture here; review feedback is still useful
+      }
+    }
     const review = await readOptional(join(input.projectPath, 'reviews/chapter', chapterReviewFileName(input.chapterNumber)));
     if (review) parts.push(`## Editor Review\n${review}`);
     if (input.feedback) parts.push(`## Additional Feedback\n${input.feedback}`);

package/src/core/fileNames.ts

@@ -46,3 +46,8 @@ export function chapterVersionFileName(chapterNumber: number, timestamp: string)
   const safeTs = timestamp.replace(/[:.]/g, '-');
   return `${padChapterNumber(chapterNumber)}.${safeTs}.md`;
 }
+
+export function storyBibleVersionFileName(timestamp: string): string {
+  const safeTs = timestamp.replace(/[:.]/g, '-');
+  return `story-bible.${safeTs}.md`;
+}

package/src/core/index.ts

@@ -7,3 +7,7 @@ export * from './contextBuilder.js';
 export * from './prompts.js';
 export * from './retrieval/index.js';
 export * from './projectDiscovery.js';
+export * from './threadStore.js';
+export * from './bibleStore.js';
+export * from './projectOps.js';
+export * from './characterStore.js';