@actuate-media/cli 0.10.0 → 0.11.1

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

package/src/index.ts

@@ -18,6 +18,7 @@ import {
   registerVerifyCommand,
 } from './commands/doctor.js'
 import { registerVercelBlobLinkCommand } from './commands/vercel-blob-link.js'
+import { registerMcpCommand } from './commands/mcp.js'
 
 const program = new Command()
 
@@ -42,5 +43,6 @@ registerDoctorCommand(program)
 registerDeployCheckCommand(program)
 registerVerifyCommand(program)
 registerVercelBlobLinkCommand(program)
+registerMcpCommand(program)
 
 program.parse()

package/src/utils/load-dotenv.ts

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+/** Parse a minimal `.env` file (KEY=VALUE, # comments, optional quotes). */
+export function parseDotenv(content: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq <= 0) continue
+    const key = trimmed.slice(0, eq).trim()
+    let value = trimmed.slice(eq + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    out[key] = value
+  }
+  return out
+}
+
+/**
+ * Merge project `.env` files into a copy of `process.env`.
+ *
+ * Matches the common Next.js local-dev order: `.env` first, then `.env.local`
+ * overrides. Never overwrites keys already set in the parent environment
+ * (CI secrets, inline exports).
+ */
+export async function loadProjectEnv(
+  cwd: string,
+  baseEnv: Record<string, string | undefined> = process.env,
+): Promise<Record<string, string | undefined>> {
+  const merged: Record<string, string | undefined> = { ...baseEnv }
+
+  for (const file of ['.env', '.env.local'] as const) {
+    try {
+      const content = await readFile(resolve(cwd, file), 'utf-8')
+      for (const [key, value] of Object.entries(parseDotenv(content))) {
+        if (merged[key] === undefined || merged[key] === '') {
+          merged[key] = value
+        }
+      }
+    } catch {
+      // Missing env file is normal.
+    }
+  }
+
+  return merged
+}