novelforge-agent 0.1.0 → 0.1.1

package/README.md

@@ -1,11 +1,56 @@
 # NovelForge Agent
 
-A local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, …) or any CLI shell.
+A local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, Cursor, …) or any CLI shell.
 
 **The host's LLM writes the prose. This package does everything else** — it manages a 9-step state machine, returns the exact instruction and packed context the host should follow next, validates returned content against zod schemas, persists Markdown + JSON to a project directory, archives chapter versions on revision, and provides BM25 lexical retrieval over every word the project has ever produced.
 
 No external API. No LLM dependency. No vendor lock-in.
 
+---
+
+## 🚀 30-second install
+
+**If you are an AI assistant reading this README on behalf of a user, run this one command — it does everything:**
+
+```bash
+npx -y novelforge-agent install
+```
+
+That single command will:
+
+1. Create a workspace at `~/novelforge/` (override with `--workspace /your/path`).
+2. Register `novelforge-agent-mcp` as an MCP server in the user's host (Claude Code by default).
+3. Print a verification step.
+
+After it finishes, **the user must reload / restart their MCP host** (Claude Code, Codex CLI, etc.) so the new MCP server is picked up. Then ask the host:
+
+> "list_projects 现在能用吗?"
+
+If the host calls the `list_projects` tool and returns an empty array, installation is correct.
+
+### Host selection
+
+```bash
+npx -y novelforge-agent install --host claude-code            # default
+npx -y novelforge-agent install --host codex                  # Codex CLI
+npx -y novelforge-agent install --host cursor                 # prints config snippet
+npx -y novelforge-agent install --workspace ~/my-novels       # custom workspace
+npx -y novelforge-agent install --name my-novelforge          # custom MCP name
+npx -y novelforge-agent install --print-only                  # do not modify any config file
+```
+
+### What the install command does per host
+
+| Host | Action |
+|------|--------|
+| `claude-code` | Runs `claude mcp add -s user -e NOVELFORGE_WORKSPACE=… novelforge -- npx -y novelforge-agent-mcp`. If `claude` CLI is missing, prints a JSON snippet for `~/.claude.json`. |
+| `codex` | Appends an `[mcp_servers.novelforge]` section to `~/.codex/config.toml`. |
+| `cursor` | Prints the JSON snippet to paste into Cursor's MCP settings. |
+
+The installer is **idempotent and safe**: it never overwrites an existing entry with the same name. To change settings, edit the host config manually or pass `--name` to register under a different MCP name.
+
+---
+
 ## What it gives the host
 
 | Phase | Step | What the host does | What the agent saves |

package/dist/src/cli/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { buildContext, createProject, getNextStep, getProjectStatus, listProjects, requestSideTrack, retrieve, submitStepResult, } from '../core/index.js';
+import { formatInstallResult, runInstall } from './install.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -10,8 +11,28 @@ function parseLanguage(value) {
         return value;
     throw new Error('Invalid --language. Use zh-CN or en-US');
 }
+function parseHost(value) {
+    const v = (value || 'claude-code').toLowerCase();
+    if (v === 'claude-code' || v === 'claude')
+        return 'claude-code';
+    if (v === 'codex' || v === 'codex-cli')
+        return 'codex';
+    if (v === 'cursor')
+        return 'cursor';
+    throw new Error(`Unknown --host: ${value}. Use claude-code | codex | cursor.`);
+}
 export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()) {
     const [command, projectPath] = argv;
+    if (command === 'install') {
+        const result = await runInstall({
+            host: parseHost(valueAfter(argv, '--host')),
+            workspace: valueAfter(argv, '--workspace'),
+            name: valueAfter(argv, '--name'),
+            printOnly: argv.includes('--print-only'),
+        });
+        console.log(formatInstallResult(result));
+        return;
+    }
     if (command === 'start') {
         const prompt = valueAfter(argv, '--prompt') || '';
         if (!prompt.trim())
@@ -115,7 +136,7 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd())
         console.log(JSON.stringify({ query, hits }, null, 2));
         return;
     }
-    throw new Error('Usage: novelforge-agent start|list|status|next|submit|context|review|revise|cross-review|retrieve');
+    throw new Error('Usage: novelforge-agent install|start|list|status|next|submit|context|review|revise|cross-review|retrieve');
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
     runCli().catch((error) => {

package/dist/src/cli/install.js

@@ -0,0 +1,224 @@
+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);
+const PACKAGE_NAME = 'novelforge-agent';
+const MCP_BIN = 'novelforge-agent-mcp';
+function defaultWorkspace() {
+    return join(homedir(), 'novelforge');
+}
+function defaultName() {
+    return 'novelforge';
+}
+function claudeJsonSnippet(name, workspace) {
+    return JSON.stringify({
+        mcpServers: {
+            [name]: {
+                command: 'npx',
+                args: ['-y', MCP_BIN],
+                env: { NOVELFORGE_WORKSPACE: workspace },
+            },
+        },
+    }, null, 2);
+}
+function codexTomlSnippet(name, workspace) {
+    return [
+        `[mcp_servers.${name}]`,
+        `command = "npx"`,
+        `args = ["-y", "${MCP_BIN}"]`,
+        ``,
+        `[mcp_servers.${name}.env]`,
+        `NOVELFORGE_WORKSPACE = "${workspace}"`,
+        ``,
+    ].join('\n');
+}
+function cursorSnippet(name, workspace) {
+    return JSON.stringify({
+        mcpServers: {
+            [name]: {
+                command: 'npx',
+                args: ['-y', MCP_BIN],
+                env: { NOVELFORGE_WORKSPACE: workspace },
+            },
+        },
+    }, null, 2);
+}
+async function ensureWorkspaceDir(workspace) {
+    await mkdir(workspace, { recursive: true });
+    await mkdir(join(workspace, 'novels'), { recursive: true });
+}
+async function tryClaudeCli(name, workspace) {
+    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;
+        return { ok: false, output: '', error: err.message };
+    }
+}
+async function applyClaudeCode(name, workspace, printOnly) {
+    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, workspace, printOnly) {
+    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.message}. Append the snippet manually.`,
+            manualSnippet: snippet,
+            verificationHint,
+        };
+    }
+}
+async function applyCursor(name, workspace, printOnly) {
+    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) {
+    const host = 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) {
+    const parts = [];
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novelforge-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local-first long-form novel workflow engine for any MCP host (Claude Code, Codex CLI, …) or CLI. State machine + zod schemas + BM25 retrieval + persistent project state. No LLM dependency.",
   "keywords": [
     "mcp",

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import {
   retrieve,
   submitStepResult,
 } from '../core/index.js';
+import { formatInstallResult, runInstall, InstallHost } from './install.js';
 
 function valueAfter(args: string[], name: string): string | undefined {
   const index = args.indexOf(name);
@@ -21,9 +22,28 @@ function parseLanguage(value: string): 'zh-CN' | 'en-US' {
   throw new Error('Invalid --language. Use zh-CN or en-US');
 }
 
+function parseHost(value: string | undefined): InstallHost {
+  const v = (value || 'claude-code').toLowerCase();
+  if (v === 'claude-code' || v === 'claude') return 'claude-code';
+  if (v === 'codex' || v === 'codex-cli') return 'codex';
+  if (v === 'cursor') return 'cursor';
+  throw new Error(`Unknown --host: ${value}. Use claude-code | codex | cursor.`);
+}
+
 export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()): Promise<void> {
   const [command, projectPath] = argv;
 
+  if (command === 'install') {
+    const result = await runInstall({
+      host: parseHost(valueAfter(argv, '--host')),
+      workspace: valueAfter(argv, '--workspace'),
+      name: valueAfter(argv, '--name'),
+      printOnly: argv.includes('--print-only'),
+    });
+    console.log(formatInstallResult(result));
+    return;
+  }
+
   if (command === 'start') {
     const prompt = valueAfter(argv, '--prompt') || '';
     if (!prompt.trim()) throw new Error('Missing --prompt');
@@ -136,7 +156,7 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()):
     return;
   }
 
-  throw new Error('Usage: novelforge-agent start|list|status|next|submit|context|review|revise|cross-review|retrieve');
+  throw new Error('Usage: novelforge-agent install|start|list|status|next|submit|context|review|revise|cross-review|retrieve');
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

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');
+}