@actuate-media/cli 0.8.0 → 0.11.0

package/src/__tests__/mcp-init.test.ts

@@ -0,0 +1,125 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { Command } from 'commander'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { registerMcpCommand } from '../commands/mcp.js'
+
+/**
+ * `actuate mcp:init` retrofits MCP editor configs onto existing projects.
+ * Pins the merge contract: other configured servers are never clobbered, an
+ * existing `actuate` entry needs `--force`, and both config paths end up
+ * git-ignored (they hold a real API key once configured).
+ */
+
+let projectDir: string
+let originalCwd: string
+
+async function run(args: string[] = []): Promise<void> {
+  const program = new Command()
+  program.exitOverride()
+  registerMcpCommand(program)
+  await program.parseAsync(['mcp:init', ...args], { from: 'user' })
+}
+
+async function readJson(relPath: string): Promise<any> {
+  return JSON.parse(await readFile(path.join(projectDir, relPath), 'utf8'))
+}
+
+beforeEach(async () => {
+  originalCwd = process.cwd()
+  projectDir = await mkdtemp(path.join(tmpdir(), 'actuate-mcp-init-'))
+  process.chdir(projectDir)
+})
+
+afterEach(async () => {
+  process.chdir(originalCwd)
+  process.exitCode = 0
+  await rm(projectDir, { recursive: true, force: true })
+})
+
+describe('mcp:init', () => {
+  it('creates both editor configs with placeholder key and git-ignores them', async () => {
+    await writeFile(path.join(projectDir, '.gitignore'), 'node_modules\n', 'utf8')
+    await run()
+
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.command).toBe('npx')
+    expect(cursor.mcpServers.actuate.args).toEqual(['-y', '@actuate-media/mcp-server'])
+    expect(cursor.mcpServers.actuate.env.ACTUATE_BASE_URL).toBe('http://localhost:3000')
+    expect(cursor.mcpServers.actuate.env.ACTUATE_API_KEY).toBe('act_sk_REPLACE_WITH_YOUR_KEY')
+
+    const vscode = await readJson('.vscode/mcp.json')
+    expect(vscode.servers.actuate.type).toBe('stdio')
+
+    const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8')
+    expect(gitignore).toContain('node_modules')
+    expect(gitignore).toContain('.cursor/mcp.json')
+    expect(gitignore).toContain('.vscode/mcp.json')
+  })
+
+  it('applies --url and --key to both configs', async () => {
+    await run(['--url', 'https://example.com', '--key', 'act_sk_real123'])
+
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.env).toEqual({
+      ACTUATE_BASE_URL: 'https://example.com',
+      ACTUATE_API_KEY: 'act_sk_real123',
+    })
+    const vscode = await readJson('.vscode/mcp.json')
+    expect(vscode.servers.actuate.env.ACTUATE_BASE_URL).toBe('https://example.com')
+  })
+
+  it('merges into an existing config without clobbering other servers', async () => {
+    await mkdir(path.join(projectDir, '.cursor'), { recursive: true })
+    await writeFile(
+      path.join(projectDir, '.cursor', 'mcp.json'),
+      JSON.stringify({ mcpServers: { sentry: { command: 'sentry-mcp' } } }),
+      'utf8',
+    )
+    await run()
+
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.sentry).toEqual({ command: 'sentry-mcp' })
+    expect(cursor.mcpServers.actuate).toBeDefined()
+  })
+
+  it('leaves an existing actuate entry alone unless --force is passed', async () => {
+    await mkdir(path.join(projectDir, '.cursor'), { recursive: true })
+    const existing = {
+      mcpServers: { actuate: { command: 'custom', env: { ACTUATE_BASE_URL: 'https://keep.me' } } },
+    }
+    await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), JSON.stringify(existing), 'utf8')
+
+    await run()
+    let cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.command).toBe('custom')
+
+    await run(['--force', '--url', 'https://new.example.com'])
+    cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate.command).toBe('npx')
+    expect(cursor.mcpServers.actuate.env.ACTUATE_BASE_URL).toBe('https://new.example.com')
+  })
+
+  it('fails on invalid JSON without --force, overwrites with --force', async () => {
+    await mkdir(path.join(projectDir, '.cursor'), { recursive: true })
+    await writeFile(path.join(projectDir, '.cursor', 'mcp.json'), '{ not json', 'utf8')
+
+    await run()
+    expect(process.exitCode).toBe(1)
+    process.exitCode = 0
+
+    await run(['--force'])
+    const cursor = await readJson('.cursor/mcp.json')
+    expect(cursor.mcpServers.actuate).toBeDefined()
+  })
+
+  it('does not duplicate gitignore entries on re-runs', async () => {
+    await run()
+    await run(['--force'])
+    const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8')
+    const count = gitignore.split('\n').filter((l) => l.trim() === '.cursor/mcp.json').length
+    expect(count).toBe(1)
+  })
+})

package/src/__tests__/seed.test.ts

@@ -130,6 +130,103 @@ describe('seed document creation', () => {
   })
 })
 
+describe('seed document upsert', () => {
+  function makeDb(existing: { id: string; status: string; publishedAt: Date | null } | null) {
+    const tx = {
+      document: {
+        create: vi.fn().mockResolvedValue({ id: 'doc-new' }),
+        update: vi.fn().mockResolvedValue({ id: existing?.id ?? 'doc-new' }),
+      },
+      version: { create: vi.fn() },
+    }
+    const db = {
+      document: { findFirst: vi.fn().mockResolvedValue(existing) },
+      $transaction: vi.fn(async (fn: any) => fn(tx)),
+    }
+    return { db, tx }
+  }
+
+  const doc = {
+    collection: 'pages',
+    status: 'PUBLISHED',
+    data: { title: 'Home v2', slug: 'home' },
+  }
+
+  it('updates an existing document matched by collection + slug', async () => {
+    const publishedAt = new Date('2026-01-01T00:00:00Z')
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'PUBLISHED', publishedAt })
+
+    const result = await createSeedDocument(db, 'admin-1', doc, { upsert: true })
+
+    expect(result).toBe('updated')
+    expect(db.document.findFirst).toHaveBeenCalledWith({
+      where: { collection: 'pages', slug: 'home', deletedAt: null },
+      select: { id: true, status: true, publishedAt: true },
+    })
+    expect(tx.document.create).not.toHaveBeenCalled()
+    expect(tx.document.update).toHaveBeenCalledWith({
+      where: { id: 'doc-1' },
+      data: expect.objectContaining({
+        title: 'Home v2',
+        status: 'PUBLISHED',
+        // Re-publishing an already-published doc keeps the original timestamp.
+        publishedAt,
+        updatedById: 'admin-1',
+      }),
+    })
+    expect(tx.version.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({ documentId: 'doc-1', changeType: 'UPDATE' }),
+    })
+  })
+
+  it('stamps publishedAt on the transition into PUBLISHED', async () => {
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'DRAFT', publishedAt: null })
+
+    await createSeedDocument(db, 'admin-1', doc, { upsert: true })
+
+    expect(tx.document.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ publishedAt: expect.any(Date) }),
+      }),
+    )
+  })
+
+  it('creates when no document matches', async () => {
+    const { db, tx } = makeDb(null)
+
+    const result = await createSeedDocument(db, 'admin-1', doc, { upsert: true })
+
+    expect(result).toBe('created')
+    expect(tx.document.create).toHaveBeenCalled()
+    expect(tx.document.update).not.toHaveBeenCalled()
+  })
+
+  it('always creates slugless documents (no upsert key)', async () => {
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'DRAFT', publishedAt: null })
+
+    const result = await createSeedDocument(
+      db,
+      'admin-1',
+      { collection: 'pages', status: 'DRAFT', data: { title: 'No slug' } },
+      { upsert: true },
+    )
+
+    expect(result).toBe('created')
+    expect(db.document.findFirst).not.toHaveBeenCalled()
+    expect(tx.document.create).toHaveBeenCalled()
+  })
+
+  it('does not look up existing documents without the upsert flag', async () => {
+    const { db, tx } = makeDb({ id: 'doc-1', status: 'DRAFT', publishedAt: null })
+
+    const result = await createSeedDocument(db, 'admin-1', doc)
+
+    expect(result).toBe('created')
+    expect(db.document.findFirst).not.toHaveBeenCalled()
+    expect(tx.document.create).toHaveBeenCalled()
+  })
+})
+
 describe('demo navigations', () => {
   // The scaffold site layout fetches menus by the `main` and `footer` slugs, so
   // the demo seed must provide exactly those — guard against slug drift.

package/src/commands/mcp.ts

@@ -0,0 +1,181 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { logger } from '../utils/logger.js'
+
+/**
+ * `actuate mcp:init` — retrofit the Actuate MCP server config onto an
+ * existing project.
+ *
+ * New scaffolds (`npm create actuate-cms`) emit `.cursor/mcp.json` and
+ * `.vscode/mcp.json` automatically; projects created before that feature (or
+ * set up by hand) have no easy path. This command writes both editor configs,
+ * merging into existing files so other MCP servers are preserved, and ensures
+ * both paths are git-ignored (a real `act_sk_...` key pasted into them must
+ * never be committed).
+ */
+
+interface McpInitOptions {
+  url: string
+  key: string
+  force?: boolean
+}
+
+const PLACEHOLDER_KEY = 'act_sk_REPLACE_WITH_YOUR_KEY'
+
+/** Cursor / Claude Desktop shape: top-level `mcpServers`. */
+function cursorEntry(opts: McpInitOptions): Record<string, unknown> {
+  return {
+    command: 'npx',
+    args: ['-y', '@actuate-media/mcp-server'],
+    env: { ACTUATE_BASE_URL: opts.url, ACTUATE_API_KEY: opts.key },
+  }
+}
+
+/** VS Code shape: top-level `servers`, each entry declares `type: "stdio"`. */
+function vscodeEntry(opts: McpInitOptions): Record<string, unknown> {
+  return { type: 'stdio', ...cursorEntry(opts) }
+}
+
+interface MergeTarget {
+  /** Path relative to the project root, also used in log lines. */
+  relPath: string
+  /** Top-level key the editor expects (`mcpServers` vs `servers`). */
+  rootKey: 'mcpServers' | 'servers'
+  entry: Record<string, unknown>
+}
+
+type MergeResult = 'created' | 'updated' | 'skipped' | 'error'
+
+/**
+ * Create or merge one editor config. Existing files keep every other server
+ * entry; an existing `actuate` entry is only replaced with `--force`.
+ */
+async function mergeConfigFile(
+  root: string,
+  target: MergeTarget,
+  force: boolean,
+): Promise<MergeResult> {
+  const filePath = path.join(root, target.relPath)
+
+  let config: Record<string, unknown> = {}
+  let existed = false
+  if (existsSync(filePath)) {
+    existed = true
+    const raw = await readFile(filePath, 'utf8')
+    try {
+      const parsed = JSON.parse(raw) as unknown
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        config = parsed as Record<string, unknown>
+      } else if (!force) {
+        logger.error(`${target.relPath} is not a JSON object — fix it or re-run with --force.`)
+        return 'error'
+      }
+    } catch {
+      if (!force) {
+        logger.error(`${target.relPath} contains invalid JSON — fix it or re-run with --force.`)
+        return 'error'
+      }
+      config = {}
+    }
+  }
+
+  const serversRaw = config[target.rootKey]
+  const servers =
+    serversRaw && typeof serversRaw === 'object' && !Array.isArray(serversRaw)
+      ? (serversRaw as Record<string, unknown>)
+      : {}
+
+  if (servers.actuate && !force) {
+    logger.warn(`${target.relPath} already has an "actuate" server — use --force to replace it.`)
+    return 'skipped'
+  }
+
+  config[target.rootKey] = { ...servers, actuate: target.entry }
+
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8')
+  return existed ? 'updated' : 'created'
+}
+
+/**
+ * Make sure both MCP config paths are git-ignored. Appends only the missing
+ * entries; creates `.gitignore` if the project somehow has none.
+ */
+async function ensureGitignored(root: string, relPaths: string[]): Promise<string[]> {
+  const gitignorePath = path.join(root, '.gitignore')
+  const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, 'utf8') : ''
+  const lines = new Set(existing.split(/\r?\n/).map((l) => l.trim()))
+  const missing = relPaths.filter((p) => !lines.has(p))
+  if (missing.length === 0) return []
+
+  const block =
+    (existing && !existing.endsWith('\n') ? '\n' : '') +
+    '\n# MCP configs hold a real API key once configured — never commit them\n' +
+    missing.join('\n') +
+    '\n'
+  await writeFile(gitignorePath, existing + block, 'utf8')
+  return missing
+}
+
+export function registerMcpCommand(program: Command): void {
+  program
+    .command('mcp:init')
+    .description('Write .cursor/mcp.json + .vscode/mcp.json wiring the Actuate MCP server')
+    .option('--url <baseUrl>', 'Base URL of the running CMS', 'http://localhost:3000')
+    .option('--key <apiKey>', 'Actuate API key (act_sk_...)', PLACEHOLDER_KEY)
+    .option('--force', 'Replace an existing "actuate" server entry (or unparseable config)')
+    .action(async (opts: McpInitOptions) => {
+      const root = process.cwd()
+
+      if (opts.key !== PLACEHOLDER_KEY && !opts.key.startsWith('act_sk_')) {
+        logger.warn(
+          'The provided --key does not look like an Actuate API key (expected act_sk_ prefix).',
+        )
+      }
+
+      const targets: MergeTarget[] = [
+        { relPath: '.cursor/mcp.json', rootKey: 'mcpServers', entry: cursorEntry(opts) },
+        { relPath: '.vscode/mcp.json', rootKey: 'servers', entry: vscodeEntry(opts) },
+      ]
+
+      let failed = false
+      for (const target of targets) {
+        const result = await mergeConfigFile(root, target, Boolean(opts.force))
+        if (result === 'created') logger.success(`Created ${target.relPath}`)
+        else if (result === 'updated') logger.success(`Updated ${target.relPath}`)
+        else if (result === 'error') failed = true
+      }
+
+      const ignored = await ensureGitignored(
+        root,
+        targets.map((t) => t.relPath),
+      )
+      if (ignored.length > 0) {
+        logger.success(`Added to .gitignore: ${ignored.join(', ')}`)
+      }
+
+      console.log()
+      console.log(chalk.bold('Next steps'))
+      if (opts.key === PLACEHOLDER_KEY) {
+        console.log(
+          `  1. Mint an API key in ${chalk.cyan('Admin → Settings → API Keys')} (act_sk_...)`,
+        )
+        console.log(
+          `  2. Replace ${chalk.cyan(PLACEHOLDER_KEY)} in both config files with the real key`,
+        )
+        console.log('  3. Restart Cursor / VS Code so the MCP server is picked up')
+      } else {
+        console.log('  1. Restart Cursor / VS Code so the MCP server is picked up')
+      }
+      if (opts.url === 'http://localhost:3000') {
+        console.log(
+          chalk.dim('  Tip: pass --url https://your-site.com to target a deployed CMS instead.'),
+        )
+      }
+
+      if (failed) process.exitCode = 1
+    })
+}