novelforge-agent 0.1.0 → 0.2.0

package/src/core/projectOps.ts

@@ -0,0 +1,243 @@
+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'],
+  architecture: ['architecture'],
+  continuity_review: ['continuityReview'],
+};
+
+const STEP_FILE_PATHS: Partial<Record<WorkflowStep, string[]>> = {
+  novel_metadata: ['novel.json'],
+  story_bible: ['story-bible.md'],
+  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 === '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

@@ -30,6 +30,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,6 +48,16 @@ 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';

package/src/core/prompts/en-US.ts

@@ -106,6 +106,18 @@ Output valid JSON only, in this shape:
       "order": 1
     }
   ],
+  "volumePacing": [
+    {
+      "volumeId": "v1",
+      "start": "Volume starting state: protagonist/world/conflict",
+      "promise": "Core reader promise or question for this volume",
+      "keyTurns": ["Key turn 1", "Key turn 2"],
+      "midpoint": "Midpoint turn or changed understanding",
+      "climax": "Volume climax",
+      "payoffs": ["Threads or promises this volume plans to pay off"],
+      "lingeringMysteries": ["Mysteries intentionally left open at volume end"]
+    }
+  ],
   "chapters": [
     {
       "chapterNumber": 1,
@@ -121,50 +133,64 @@ Rules:
 - chapters.length must be at least ${input.state.targetChapters}.
 - chapterNumber must start at 1 and increase contiguously.
 - volumeId must reference an id from volumes.
+- volumePacing must provide one pacing board for every volume.
 - requiredBeats must include at least one concrete, actionable beat.
 ${strictJsonOutputRules()}`,
     };
 }
 
 function buildChapterPrompt(input: PromptBuildInput): BuiltPrompt {
-return {
-      purpose: 'chapter',
-      expectedFormat: 'Markdown',
-      prompt: `You are a professional long-form fiction writer. Write chapter ${input.state.currentChapter} directly.
+  const ch = input.state.currentChapter;
+  const isFirstChapter = ch <= 1;
+  return {
+    purpose: 'chapter',
+    expectedFormat: 'Markdown',
+    prompt: `You are a professional long-form fiction writer. Write chapter ${ch} directly.
 
 ## Priority Order
 1. Strictly follow the current chapter architecture, user additions, story bible hard constraints, and previous-chapter continuity.
-2. Use relevant memory and prior text evidence to preserve consistency.
+2. Use relevant memory, prior text evidence, and active foreshadow threads.
 3. Treat full-book and volume plans as distant planning context only. Do not write concrete future events early.
 
-## Style And Length
+## Length Target
+- Default target: ~2500 words (±20%). If the chapter architecture specifies targetWords, follow it.
+- Do not pad to hit the target; do not under-write to be brief at the cost of conflict.
+
+## Structure
+${isFirstChapter
+  ? '- This is chapter 1. No recap needed. Open with character and situation directly.'
+  : '- Start with a 2-3 sentence recap or bridge so a reader who skipped the last chapter can re-enter (unless the chapter architecture has requireRecap=false). Make it natural, not meta-narration like "previously...".'}
+- The chapter must end on a clear hook: cliffhanger, mystery, emotional resonance, reveal, or volume close — per the chapter architecture endHookFocus. Default: cliffhanger.
+
+## Style
 - Match the novel's genre, world, character identities, and emotional tone.
-- Keep the language natural, stable, and readable. Prioritize narrative progress, character work, and emotional accumulation.
-- Dialogue must fit each character's identity, relationship, and immediate situation.
-- Important emotion should appear through action, body language, pacing, and subtext where possible.
-- Scene description should provide useful sensory and atmospheric detail, but never stall the plot.
-- Conflict, turns, suspense, and the chapter-end hook should be clear.
+- Natural, stable, readable language; prioritize narrative progress, character work, and emotional accumulation.
+- Dialogue fits each character's identity, relationship, and situation.
+- Important emotion comes through action, body language, pacing, and subtext.
+- Scene description has useful sensory detail without stalling.
+- POV: strictly follow the chapter architecture povCharacter (if set). No mid-chapter POV switch.
 
 ## Execution Rules
 - Write only what the current chapter architecture authorizes.
-- Do not introduce unauthorized major characters. Functional background characters should stay light.
-- Keep names, items, places, abilities, timeline, injuries, relationships, and knowledge boundaries consistent.
-- If the previous chapter ends mid-action, mid-dialogue, or in the same scene, this chapter must continue from that point.
+- Do not introduce unauthorized major characters. Functional background characters stay light.
+- Keep names, items, places, abilities, timelines, injuries, relationships, and knowledge boundaries consistent.
+- If the previous chapter ends mid-action or mid-scene, this chapter must continue from that point.
+- Active foreshadow threads may be advanced or paid off this chapter, but **never silently dropped** — even if you choose not to touch them, leave them coherent.
 - Avoid cost-free power jumps, forced stupidity, mechanical twists, info-dumps, and empty lyricism.
-- Do not output summaries, bullet points, lectures, or explanatory prefaces.
+- Do not output summaries, bullet points, lectures, explanatory prefaces, or meta-text like "what I changed".
 
 ${input.context ? `## Generation Context\n${input.context}\n` : ''}## Output Requirements
 - Output Markdown.
 - First line must be the chapter title as H1, for example: # Chapter Title
 - After the H1, begin the prose directly.`,
-    };
+  };
 }
 
 function buildMemoryPrompt(input: PromptBuildInput): BuiltPrompt {
-return {
-      purpose: 'memory_card',
-      expectedFormat: 'JSON matching MemoryCardSchema',
-      prompt: `You are a continuity editor for a long-form novel. Extract a memory card from chapter ${input.state.currentChapter}.
+  return {
+    purpose: 'memory_card',
+    expectedFormat: 'JSON matching MemoryCardSchema',
+    prompt: `You are a continuity editor for a long-form novel. Extract a memory card from chapter ${input.state.currentChapter}.
 
 ${input.context ? `## Current Chapter Context\n${input.context}\n` : ''}## Output Requirements
 Output valid JSON only, in this shape:
@@ -192,15 +218,43 @@ Output valid JSON only, in this shape:
       "after": "After"
     }
   ],
-  "openThreads": ["Unresolved promise, danger, question, or plot thread"]
+  "openThreads": ["Unresolved promise, danger, question, or plot thread"],
+  "wordCount": <approximate word count of this chapter as an integer>,
+  "threadActions": [
+    {
+      "kind": "plant | build | pay | drop",
+      "threadId": "id of an existing active thread (required for build/pay/drop; leave empty for plant — the system will assign one)",
+      "description": "for plant: what the new thread is; for others: one sentence on how this chapter advanced/paid/dropped that thread"
+    }
+  ],
+  "characterUpdates": [
+    {
+      "name": "Character name",
+      "role": "Role if confirmed or changed this chapter",
+      "goal": "Current goal at chapter end",
+      "belief": "Core belief or understanding driving them at chapter end",
+      "relationships": [
+        { "name": "Related character", "dynamic": "Relationship state at chapter end" }
+      ],
+      "abilities": ["Abilities, resources, or limits confirmed at chapter end"],
+      "secrets": ["Secrets still hidden or only partially known at chapter end"],
+      "emotionalState": "Emotional state at chapter end"
+    }
+  ]
 }
 
 Rules:
 - Record only information that happened or was confirmed in this chapter.
 - Do not speculate about future plot.
 - Make facts and stateChanges concrete enough for later chapter reference.
+- wordCount: approximate word count (English) or character count (CJK). An integer estimate is fine.
+- threadActions is critical:
+  · For any active foreshadow thread in the context's "Active Foreshadow Threads" section, if this chapter advanced it emit kind="build"; if this chapter paid it off emit kind="pay"; if this chapter abandoned it emit kind="drop". threadId is required.
+  · For any new thread this chapter plants, emit kind="plant" with a clear description.
+  · If an active thread was not touched, no action needed — but never silently delete it. Without a drop action, the thread stays active.
+- characterUpdates maintains a separate character state table. Emit only important characters whose state changed or was reconfirmed in this chapter; goal, belief, relationships, abilities, secrets, and emotionalState must reflect the chapter ending.
 ${strictJsonOutputRules()}`,
-    };
+  };
 }
 
 function buildContinuityReviewPrompt(input: PromptBuildInput): BuiltPrompt {
@@ -250,6 +304,12 @@ return {
       prompt: `You are a strict editor reviewing a single chapter of a serial novel for in-chapter problems and conflicts with established context.
 
 ${input.context ? `## Review Context\n${input.context}\n` : ''}## Review Focus
+- This is a mandatory chapter acceptance gate. If any acceptance item fails, status must be "issues_found" and the workflow must revise before continuing.
+- Whether every requiredBeat is fulfilled; missing beats must appear in acceptance.requiredBeats.missingBeats.
+- Whether this chapter advances the main line, character state, or active foreshadow threads. If it is static, at least one of narrativeProgress/characterProgress/foreshadowProgress must fail.
+- Whether it violates the story bible, character state table, volume pacing board, or prior memory.
+- Whether the ending has a clear hook that matches the chapter architecture endHookFocus.
+- Whether it repeats prior chapter beats, conflict patterns, reveals, or dialogue functions.
 - Character voice, motivation, and state vs the story bible and prior memory.
 - World rules, item ownership, and ability limits.
 - Timeline, location, and continuity with the previous chapter ending.
@@ -261,6 +321,37 @@ Output valid JSON only, in this shape:
 {
   "chapterNumber": ${chapter},
   "status": "clean",
+  "acceptance": {
+    "requiredBeats": {
+      "status": "pass | fail",
+      "evidence": "Evidence for each requiredBeat",
+      "missingBeats": []
+    },
+    "narrativeProgress": {
+      "status": "pass | fail",
+      "evidence": "How this chapter advances the main line or phase objective"
+    },
+    "characterProgress": {
+      "status": "pass | fail",
+      "evidence": "How this chapter changes or confirms key character goal, belief, relationship, ability, secret, or emotion"
+    },
+    "foreshadowProgress": {
+      "status": "pass | fail",
+      "evidence": "How this chapter plants, advances, pays, or deliberately preserves foreshadow threads"
+    },
+    "storyBibleConsistency": {
+      "status": "pass | fail",
+      "evidence": "Whether it matches the story bible, character state table, and world rules"
+    },
+    "endingHook": {
+      "status": "pass | fail",
+      "evidence": "The ending hook passage and its function"
+    },
+    "repetition": {
+      "status": "pass | fail",
+      "evidence": "Whether it repeats prior beats; if not, explain why"
+    }
+  },
   "issues": [
     {
       "severity": "low | medium | high",
@@ -275,6 +366,8 @@ Output valid JSON only, in this shape:
 Rules:
 - If there are no issues, use status "clean" with an empty issues array.
 - Otherwise use status "issues_found".
+- status may be "clean" only when every acceptance item is "pass".
+- If any acceptance item is "fail", include a matching issue with a concrete fix.
 - evidence must be specific; do not write "possibly" or "maybe".
 ${strictJsonOutputRules()}`,
     };
@@ -361,6 +454,17 @@ function buildPromptForStep(input: PromptBuildInput): BuiltPrompt {
       return buildChapterRevisionPrompt(input);
     case 'cross_chapter_review':
       return buildCrossChapterReviewPrompt(input);
+    case 'story_bible_amend':
+      return {
+        purpose: 'story_bible',
+        expectedFormat: 'Markdown',
+        prompt: `Based on the current story bible and the amendment context, output the FULL revised story bible Markdown.
+
+${input.context ? `## Amendment Context\n${input.context}\n` : ''}## Output Requirements
+- Output the entire story-bible.md content — it replaces the old one (old version auto-archived under story-bible-versions/).
+- Preserve everything that still holds; modify / add / remove only what the amendment context justifies.
+- Do not output diff markers, change logs, or bullet summaries — just the new full bible.`,
+      };
     case 'complete':
       return {
         purpose: 'continuity_review',

package/src/core/prompts/types.ts

@@ -9,7 +9,8 @@ export type PromptPurpose =
   | 'continuity_review'
   | 'chapter_review'
   | 'chapter_revision'
-  | 'cross_chapter_review';
+  | 'cross_chapter_review'
+  | 'story_bible_amend';
 
 export interface PromptBuildInput {
   state: AgentState;