novelforge-agent 0.1.1 → 0.3.0

package/src/core/contextBuilder.ts

@@ -2,9 +2,12 @@ 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'
+  | 'style_guide'
+  | 'architecture_extension'
   | 'memory_extraction'
   | 'continuity_review'
   | 'revision'
@@ -31,19 +34,36 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
   const parts: string[] = [];
   const metadata = await readOptional(join(input.projectPath, 'novel.json'));
   const storyBible = await readOptional(join(input.projectPath, 'story-bible.md'));
+  const styleGuideJson = await readOptional(join(input.projectPath, 'style-guide.json'));
   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 (styleGuideJson) parts.push(`## Style Guide\n${styleGuideJson}`);
+  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 +87,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')}`);
+      }
     }
   }
 
@@ -85,11 +117,40 @@ export async function buildContext(input: BuildContextInput): Promise<string> {
     if (memoryParts.length) parts.push(`## Memory Cards\n${memoryParts.join('\n')}`);
   }
 
+  if (input.purpose === 'architecture_extension') {
+    if (chaptersJson) parts.push(`## Existing Chapter Architecture List\n${chaptersJson}`);
+    if (volumePacingJson) parts.push(`## Existing Volume Pacing Boards\n${volumePacingJson}`);
+
+    const start = Math.max(1, (input.chapterNumber ?? 1) - 5);
+    const end = Math.max(0, (input.chapterNumber ?? 1) - 1);
+    const memoryParts: string[] = [];
+    for (let i = start; i <= end; i += 1) {
+      const memory = await readOptional(join(input.projectPath, 'memory', memoryFileName(i)));
+      if (memory) memoryParts.push(`### Chapter ${i} Memory\n${memory}`);
+    }
+    if (memoryParts.length) parts.push(`## Recent Memory Cards\n${memoryParts.join('\n')}`);
+
+    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\n${lines.join('\n')}`);
+    }
+  }
+
   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 +163,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';

package/src/core/projectDiscovery.ts

@@ -12,6 +12,7 @@ export interface ProjectSummary {
   currentStep: WorkflowStep;
   currentChapter: number;
   targetChapters: number;
+  plannedTotalChapters: number;
   completedSteps: number;
   chaptersWritten: number;
   updatedAt: string;
@@ -57,6 +58,7 @@ async function summarizeOne(projectPath: string): Promise<ProjectSummary | undef
     currentStep: state.currentStep,
     currentChapter: state.currentChapter,
     targetChapters: state.targetChapters,
+    plannedTotalChapters: state.plannedTotalChapters ?? state.targetChapters,
     completedSteps: state.completedSteps.length,
     chaptersWritten: countChapters(state),
     updatedAt: state.updatedAt,

package/src/core/projectOps.ts

@@ -0,0 +1,251 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { cp, readdir, rm, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { AgentState, WorkflowStep } from './types.js';
+import { loadState, saveState } from './projectStore.js';
+import { indexChapter, removeChapterFromIndex, removeMemoryCardFromIndex } from './retrieval/index.js';
+import { chapterFileName, memoryFileName } from './fileNames.js';
+
+// =============================================================================
+// fork_project
+// =============================================================================
+
+export interface ForkProjectInput {
+  sourceProjectPath: string;
+  label?: string;
+}
+
+export interface ForkProjectResult {
+  newProjectPath: string;
+  newProjectId: string;
+}
+
+export async function forkProject(input: ForkProjectInput): Promise<ForkProjectResult> {
+  const source = resolve(input.sourceProjectPath);
+  const state = await loadState(source);
+  const suffix = randomBytes(3).toString('hex');
+  const label = (input.label ?? 'fork').replace(/[^a-z0-9-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'fork';
+  const targetName = `${basename(source)}-${label}-${suffix}`;
+  const target = join(dirname(source), targetName);
+
+  await cp(source, target, { recursive: true });
+
+  const forkedState: AgentState = {
+    ...state,
+    projectId: randomUUID(),
+    projectPath: target,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  await saveState(forkedState);
+  return { newProjectPath: target, newProjectId: forkedState.projectId };
+}
+
+// =============================================================================
+// delete_chapter
+// =============================================================================
+
+export interface DeleteChapterInput {
+  projectPath: string;
+  chapterNumber: number;
+}
+
+export interface DeleteChapterResult {
+  removed: string[];
+  newCurrentChapter: number;
+  newCurrentStep: WorkflowStep;
+}
+
+async function tryUnlink(path: string): Promise<boolean> {
+  try {
+    await unlink(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function tryRmDirEntry(dirPath: string, prefix: string): Promise<string[]> {
+  const removed: string[] = [];
+  try {
+    const items = await readdir(dirPath);
+    for (const item of items) {
+      if (item.startsWith(prefix)) {
+        const full = join(dirPath, item);
+        try {
+          await unlink(full);
+          removed.push(full);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  } catch {
+    // dir absent
+  }
+  return removed;
+}
+
+export async function deleteChapter(input: DeleteChapterInput): Promise<DeleteChapterResult> {
+  const state = await loadState(input.projectPath);
+  const n = input.chapterNumber;
+  if (n < 1) throw new Error('chapterNumber must be >= 1');
+
+  const removed: string[] = [];
+  const chapterRel = join('chapters', chapterFileName(n));
+  if (await tryUnlink(join(state.projectPath, chapterRel))) removed.push(chapterRel);
+
+  const memoryRel = join('memory', memoryFileName(n));
+  if (await tryUnlink(join(state.projectPath, memoryRel))) removed.push(memoryRel);
+
+  // Versions of this chapter
+  const versionsRemoved = await tryRmDirEntry(
+    join(state.projectPath, 'chapters/.versions'),
+    `${chapterFileName(n).replace(/\.md$/, '')}.`
+  );
+  removed.push(...versionsRemoved);
+
+  // Per-chapter review
+  const reviewName = `chapter-${String(n).padStart(3, '0')}.json`;
+  if (await tryUnlink(join(state.projectPath, 'reviews/chapter', reviewName))) {
+    removed.push(`reviews/chapter/${reviewName}`);
+  }
+
+  // Update state.files
+  const nextFiles: Record<string, string> = { ...state.files };
+  delete nextFiles[`chapter-${n}`];
+  delete nextFiles[`memory-${n}`];
+  delete nextFiles[`review-chapter-${n}`];
+
+  // Remove this chapter and its memory card from the lexical index
+  await removeChapterFromIndex(state.projectPath, n);
+  await removeMemoryCardFromIndex(state.projectPath, n);
+
+  // Adjust state.currentChapter & currentStep if needed
+  let newCurrentChapter = state.currentChapter;
+  let newCurrentStep: WorkflowStep = state.currentStep;
+  if (state.currentChapter > n) {
+    // user deleted an earlier chapter; current pointer becomes the deleted one to be regenerated
+    newCurrentChapter = n;
+    newCurrentStep = 'chapter';
+  } else if (state.currentChapter === n + 1 && (state.currentStep === 'chapter' || state.currentStep === 'memory_card')) {
+    // we just finished chapter n and were about to do n+1; step back
+    newCurrentChapter = n;
+    newCurrentStep = 'chapter';
+  }
+
+  const nextState: AgentState = {
+    ...state,
+    files: nextFiles,
+    currentChapter: newCurrentChapter,
+    currentStep: newCurrentStep,
+    pendingAction: undefined,
+  };
+  await saveState(nextState);
+  return { removed, newCurrentChapter, newCurrentStep };
+}
+
+// =============================================================================
+// redo_step
+// =============================================================================
+
+export interface RedoStepInput {
+  projectPath: string;
+  step: WorkflowStep;
+  chapterNumber?: number;
+}
+
+export interface RedoStepResult {
+  removed: string[];
+  currentStep: WorkflowStep;
+  currentChapter: number;
+}
+
+const STEP_FILE_KEYS: Partial<Record<WorkflowStep, string[]>> = {
+  novel_metadata: ['novel'],
+  story_bible: ['storyBible'],
+  style_guide: ['styleGuide'],
+  architecture: ['architecture'],
+  continuity_review: ['continuityReview'],
+};
+
+const STEP_FILE_PATHS: Partial<Record<WorkflowStep, string[]>> = {
+  novel_metadata: ['novel.json'],
+  story_bible: ['story-bible.md'],
+  style_guide: ['style-guide.json'],
+  architecture: ['architecture/full.md', 'architecture/volumes.json', 'architecture/chapters.json'],
+};
+
+export async function redoStep(input: RedoStepInput): Promise<RedoStepResult> {
+  const state = await loadState(input.projectPath);
+  const removed: string[] = [];
+
+  if (input.step === 'chapter' || input.step === 'memory_card') {
+    const chapter = input.chapterNumber ?? state.currentChapter;
+    if (input.step === 'memory_card') {
+      const rel = join('memory', memoryFileName(chapter));
+      if (await tryUnlink(join(state.projectPath, rel))) removed.push(rel);
+      delete state.files[`memory-${chapter}`];
+    } else {
+      // chapter: also remove its memory + per-chapter review since they depend on it
+      const cRel = join('chapters', chapterFileName(chapter));
+      if (await tryUnlink(join(state.projectPath, cRel))) removed.push(cRel);
+      const mRel = join('memory', memoryFileName(chapter));
+      if (await tryUnlink(join(state.projectPath, mRel))) removed.push(mRel);
+      delete state.files[`chapter-${chapter}`];
+      delete state.files[`memory-${chapter}`];
+      await removeChapterFromIndex(state.projectPath, chapter);
+      await removeMemoryCardFromIndex(state.projectPath, chapter);
+    }
+    state.currentChapter = chapter;
+    state.currentStep = input.step;
+    state.pendingAction = undefined;
+  } else if (
+    input.step === 'novel_metadata'
+    || input.step === 'story_bible'
+    || input.step === 'style_guide'
+    || input.step === 'architecture'
+    || input.step === 'continuity_review'
+  ) {
+    const paths = STEP_FILE_PATHS[input.step] ?? [];
+    for (const p of paths) {
+      if (await tryUnlink(join(state.projectPath, p))) removed.push(p);
+    }
+    const keys = STEP_FILE_KEYS[input.step] ?? [];
+    for (const k of keys) {
+      delete state.files[k];
+    }
+    state.currentStep = input.step;
+    state.pendingAction = undefined;
+    if (input.step === 'novel_metadata') state.currentChapter = 1;
+  } else {
+    throw new Error(`redo_step does not support step: ${input.step}`);
+  }
+
+  // Trim completedSteps after the redo target
+  const idx = state.completedSteps.lastIndexOf(input.step);
+  if (idx >= 0) state.completedSteps = state.completedSteps.slice(0, idx);
+
+  await saveState(state);
+  return {
+    removed,
+    currentStep: state.currentStep,
+    currentChapter: state.currentChapter,
+  };
+}
+
+// =============================================================================
+// guards
+// =============================================================================
+
+export function assertProjectPath(workspaceRoot: string, projectPath: string): void {
+  const root = resolve(workspaceRoot);
+  const target = resolve(projectPath);
+  const rel = relative(root, target);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Refusing to operate outside workspace: ${target}`);
+  }
+}
+
+// keep tsc happy if no other refs
+void writeFile;

package/src/core/projectStore.ts

@@ -10,6 +10,7 @@ export interface CreateProjectInput {
   language?: AgentState['language'];
   outputDir?: string;
   targetChapters?: number;
+  plannedTotalChapters?: number;
 }
 
 export interface CreateProjectResult {
@@ -30,6 +31,7 @@ export async function ensureProjectDirectories(projectPath: string): Promise<voi
   await mkdir(join(projectPath, 'architecture'), { recursive: true });
   await mkdir(join(projectPath, 'chapters'), { recursive: true });
   await mkdir(join(projectPath, 'chapters/.versions'), { recursive: true });
+  await mkdir(join(projectPath, 'story-bible-versions'), { recursive: true });
   await mkdir(join(projectPath, 'memory'), { recursive: true });
   await mkdir(join(projectPath, 'reviews'), { recursive: true });
   await mkdir(join(projectPath, 'reviews/chapter'), { recursive: true });
@@ -47,10 +49,25 @@ export async function archiveChapterVersion(projectPath: string, chapterRelative
   }
 }
 
+export async function archiveStoryBible(projectPath: string, versionRelative: string): Promise<string | undefined> {
+  const sourcePath = join(projectPath, 'story-bible.md');
+  try {
+    const existing = await readFile(sourcePath, 'utf8');
+    return saveMarkdownFile(projectPath, versionRelative, existing);
+  } catch {
+    return undefined;
+  }
+}
+
 export async function createProject(input: CreateProjectInput): Promise<CreateProjectResult> {
   const workspaceRoot = resolve(input.workspaceRoot);
   const baseDir = input.outputDir || 'novels';
-  const targetChapters = Math.max(1, Math.floor(Number(input.targetChapters || 3)));
+  const hasExplicitTargetChapters = input.targetChapters !== undefined;
+  const targetChapters = Math.max(1, Math.floor(Number(input.targetChapters || 5)));
+  const plannedTotalChapters = Math.max(
+    targetChapters,
+    Math.floor(Number(input.plannedTotalChapters ?? (hasExplicitTargetChapters ? targetChapters : 12)))
+  );
   const baseSlug = makeProjectSlug(input.prompt.slice(0, 48));
   const suffix = randomBytes(3).toString('hex');
   const slug = `${baseSlug}-${suffix}`;
@@ -65,6 +82,7 @@ export async function createProject(input: CreateProjectInput): Promise<CreatePr
     initialPrompt: input.prompt,
     language: input.language || 'zh-CN',
     targetChapters,
+    plannedTotalChapters,
     currentStep: 'novel_metadata',
     currentChapter: 1,
     completedSteps: [],