@actuate-media/cli 0.3.0 → 0.4.0

package/src/commands/doctor.ts

@@ -0,0 +1,159 @@
+import { Command } from "commander";
+import { access, readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import {
+  buildDeploymentManifest,
+  createDiagnosticReport,
+  detectPackageManager,
+  type DiagnosticReport,
+} from "../deployment/diagnostics.js";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readSchemaModels(schemaPath: string): Promise<Set<string>> {
+  if (!(await fileExists(schemaPath))) return new Set();
+  const schema = await readFile(schemaPath, "utf-8");
+  const models = new Set<string>();
+  const modelRegex = /^model\s+(\w+)\s*\{/gm;
+  let match;
+  while ((match = modelRegex.exec(schema)) !== null) {
+    models.add(match[1]!);
+  }
+  return models;
+}
+
+async function readSchemaContent(schemaPath: string): Promise<string> {
+  if (!(await fileExists(schemaPath))) return "";
+  return readFile(schemaPath, "utf-8");
+}
+
+async function detectProjectPackageManager(): Promise<string> {
+  const entries = new Set(await readdir(process.cwd()));
+  return detectPackageManager(entries);
+}
+
+function printReport(title: string, report: DiagnosticReport): void {
+  console.log();
+  console.log(chalk.bold(title));
+  console.log(chalk.dim("─────────────────────────────────"));
+  for (const check of report.checks) {
+    const icon = check.status === "pass" ? chalk.green("PASS") : check.status === "warn" ? chalk.yellow("WARN") : chalk.red("FAIL");
+    console.log(`${icon} ${check.label}: ${check.message}`);
+    if (check.fix) console.log(chalk.dim(`  Fix: ${check.fix}`));
+    if (check.docs) console.log(chalk.dim(`  Docs: ${check.docs}`));
+  }
+  console.log(chalk.dim("─────────────────────────────────"));
+  console.log(`Status: ${report.status.toUpperCase()}`);
+  console.log();
+}
+
+async function buildReport(schemaPath: string, mode: "doctor" | "deploy" = "doctor") {
+  const resolvedSchema = resolve(process.cwd(), schemaPath);
+  const [schemaModels, schemaContent, packageManager] = await Promise.all([
+    readSchemaModels(resolvedSchema),
+    readSchemaContent(resolvedSchema),
+    detectProjectPackageManager(),
+  ]);
+
+  return createDiagnosticReport({
+    schemaModels,
+    schemaContent,
+    env: process.env,
+    packageManager,
+    schemaPath,
+    mode,
+  });
+}
+
+export function registerDoctorCommand(program: Command): void {
+  program
+    .command("doctor")
+    .description("Run AI-friendly preflight checks for an Actuate CMS project")
+    .option("--schema <path>", "Path to schema.prisma", "prisma/schema.prisma")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (opts: { schema: string; json?: boolean }) => {
+      const report = await buildReport(opts.schema, "doctor");
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        printReport("Actuate Doctor", report);
+      }
+      if (report.status === "fail") process.exitCode = 1;
+    });
+}
+
+export function registerDeployCheckCommand(program: Command): void {
+  program
+    .command("deploy:check")
+    .description("Check production deployment readiness for Actuate CMS")
+    .option("--schema <path>", "Path to schema.prisma", "prisma/schema.prisma")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (opts: { schema: string; json?: boolean }) => {
+      const report = await buildReport(opts.schema, "deploy");
+      if (opts.json) {
+        console.log(JSON.stringify({ ...report, manifest: buildDeploymentManifest() }, null, 2));
+      } else {
+        printReport("Actuate Deploy Check", report);
+        console.log(chalk.dim("Run `actuate verify --full` after deployment succeeds."));
+      }
+      if (report.status === "fail") process.exitCode = 1;
+    });
+}
+
+export function registerVerifyCommand(program: Command): void {
+  program
+    .command("verify")
+    .description("Verify an installed or deployed Actuate CMS project")
+    .option("--full", "Run the full verification checklist")
+    .option("--url <origin>", "Deployed site origin to verify, for example https://example.com")
+    .option("--json", "Print the deployment manifest as JSON")
+    .action(async (opts: { full?: boolean; url?: string; json?: boolean }) => {
+      const manifest = buildDeploymentManifest();
+      if (opts.json) {
+        console.log(JSON.stringify(manifest, null, 2));
+        return;
+      }
+
+      console.log();
+      console.log(chalk.bold(opts.full ? "Actuate Full Verification" : "Actuate Verification"));
+      console.log(chalk.dim("─────────────────────────────────"));
+      console.log(`PASS Manifest generated for ${manifest.packageScope} packages.`);
+      if (!opts.url) {
+        console.log("WARN No --url provided, so remote health/admin endpoints were not checked.");
+        console.log(chalk.dim("Run `actuate verify --full --url https://your-site.com` after deployment."));
+        console.log();
+        return;
+      }
+
+      const origin = opts.url.replace(/\/$/, "");
+      const healthUrl = `${origin}${manifest.routes.apiHealth}`;
+      const adminUrl = `${origin}${manifest.routes.adminDefault}`;
+      let failed = false;
+
+      for (const [label, url] of [['Health', healthUrl], ['Admin', adminUrl]] as const) {
+        try {
+          const response = await fetch(url, { method: 'GET' });
+          if (response.ok || response.status === 302 || response.status === 401) {
+            console.log(`PASS ${label} route responded at ${url}.`);
+          } else {
+            failed = true;
+            console.log(`FAIL ${label} route returned HTTP ${response.status} at ${url}.`);
+          }
+        } catch (error) {
+          failed = true;
+          const message = error instanceof Error ? error.message : String(error);
+          console.log(`FAIL ${label} route could not be reached at ${url}: ${message}`);
+        }
+      }
+      console.log();
+      if (failed) process.exitCode = 1;
+    });
+}

package/src/commands/seed.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { pathToFileURL } from "node:url";
@@ -280,9 +281,11 @@ async function runSeed(options: SeedOptions): Promise<void> {
     process.exit(1);
   }
 
+  let seededDb: { db: any; disconnect: () => Promise<void> } | null = null;
+
   try {
-    const { getDB } = await import("@actuate-media/cms-core");
-    const db = getDB<any>();
+    seededDb = await getSeedDatabase();
+    const db = seededDb.db;
 
     if (options.reset) {
       const yes = await confirm(
@@ -295,7 +298,9 @@ async function runSeed(options: SeedOptions): Promise<void> {
 
       const resetSpinner = ora("Clearing existing data…").start();
       await db.version.deleteMany({});
-      await db.mediaUsage.deleteMany({});
+      if (db.mediaUsage?.deleteMany) {
+        await db.mediaUsage.deleteMany({});
+      }
       await db.document.deleteMany({});
       resetSpinner.succeed("Existing data cleared.");
     }
@@ -311,71 +316,171 @@ async function runSeed(options: SeedOptions): Promise<void> {
     const message = err instanceof Error ? err.message : String(err);
     logger.error(`Seed failed: ${message}`);
     process.exit(1);
+  } finally {
+    await seededDb?.disconnect();
   }
 }
 
-async function seedDemoData(db: any): Promise<void> {
-  const spinner = ora("Seeding demo data…").start();
+async function getSeedDatabase(): Promise<{ db: any; disconnect: () => Promise<void> }> {
+  const { getDB, initDB, isDBInitialized } = await import("@actuate-media/cms-core");
+
+  if (isDBInitialized()) {
+    return { db: getDB<any>(), disconnect: async () => {} };
+  }
+
+  const db = await createProjectPrismaClient();
+  initDB(db);
+  return {
+    db,
+    disconnect: async () => {
+      if (typeof db.$disconnect === "function") {
+        await db.$disconnect();
+      }
+    },
+  };
+}
+
+async function createProjectPrismaClient(): Promise<any> {
+  if (!process.env.DATABASE_URL) {
+    throw new Error("DATABASE_URL is required to run seed/populate.");
+  }
+
+  const requireFromProject = createRequire(path.join(process.cwd(), "package.json"));
+  const generatedClient = path.resolve("generated", "prisma", "client.ts");
+
+  if (existsSync(generatedClient)) {
+    const [{ tsImport }, adapterModule, pgModule] = await Promise.all([
+      import("tsx/esm/api"),
+      import(pathToFileURL(requireFromProject.resolve("@prisma/adapter-pg")).href),
+      import(pathToFileURL(requireFromProject.resolve("pg")).href),
+    ]);
+    const { PrismaClient } = await tsImport(pathToFileURL(generatedClient).href, import.meta.url) as {
+      PrismaClient: new (options?: unknown) => any;
+    };
+    const { PrismaPg } = adapterModule as { PrismaPg: new (pool: unknown) => unknown };
+    const pg = (pgModule as { default?: typeof pgModule }).default ?? pgModule;
+    const pool = new (pg as any).Pool({ connectionString: process.env.DATABASE_URL });
+    const adapter = new PrismaPg(pool);
+    return new PrismaClient({ adapter } as any);
+  }
+
+  const clientModule = await import(pathToFileURL(requireFromProject.resolve("@prisma/client")).href) as {
+    PrismaClient: new () => any;
+  };
+  return new clientModule.PrismaClient();
+}
+
+export async function ensureSeedAdmin(db: any): Promise<{ id: string }> {
+  const existing = await db.user.findFirst({ where: { role: "ADMIN" } });
+  if (existing) return existing;
+
+  const email = process.env.CMS_ADMIN_EMAIL;
+  const password = process.env.CMS_ADMIN_PASSWORD;
+  const name = process.env.CMS_ADMIN_NAME ?? "Admin";
+
+  if (!email || !password) {
+    throw new Error(
+      "No admin user exists. Set CMS_ADMIN_EMAIL and CMS_ADMIN_PASSWORD before running seed, or complete the setup wizard first.",
+    );
+  }
+
+  const { createInitialAdmin } = await import("@actuate-media/cms-core");
+  const result = await createInitialAdmin(db, { email, password, name });
+  if (!result.success || !result.userId) {
+    throw new Error(result.error ?? "Failed to create initial admin user");
+  }
+
+  return { id: result.userId };
+}
 
-  let adminUser = await db.user.findFirst({ where: { role: "ADMIN" } });
-  if (!adminUser) {
-    adminUser = await db.user.create({
+function sanitizeSeedData(value: unknown, sanitizeHtml: (html: string) => string): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeSeedData(item, sanitizeHtml));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, item]) => [
+        key,
+        sanitizeSeedData(item, sanitizeHtml),
+      ]),
+    );
+  }
+  if (typeof value === "string" && /<[a-z][\s\S]*>/i.test(value)) {
+    return sanitizeHtml(value);
+  }
+  return value;
+}
+
+export async function createSeedDocument(
+  db: any,
+  userId: string,
+  doc: NormalizedSeedDocument,
+): Promise<void> {
+  const { extractPlainText, hashContent, sanitizeHtml } = await import("@actuate-media/cms-core");
+  const data = sanitizeSeedData(doc.data, sanitizeHtml) as Record<string, unknown>;
+  const serialized = JSON.stringify(data);
+  const plainText = extractPlainText(serialized);
+  const contentHash = await hashContent(serialized);
+
+  await db.$transaction(async (tx: any) => {
+    const created = await tx.document.create({
       data: {
-        email: "admin@actuatecms.dev",
-        name: "Admin",
-        role: "ADMIN",
-        isActive: true,
-        isApproved: true,
-        emailVerified: true,
+        collection: doc.collection,
+        title: typeof data.title === "string" ? data.title : null,
+        slug: typeof data.slug === "string" ? data.slug : null,
+        data,
+        status: doc.status,
+        publishedAt: doc.status === "PUBLISHED" ? new Date() : null,
+        createdById: userId,
+        updatedById: userId,
+        plainText,
+        contentHash,
       },
     });
-  }
+
+    await tx.version.create({
+      data: {
+        documentId: created.id,
+        data,
+        changedById: userId,
+        changeType: "CREATE",
+      },
+    });
+  });
+}
+
+async function seedDemoData(db: any): Promise<void> {
+  const spinner = ora("Seeding demo data…").start();
+
+  const adminUser = await ensureSeedAdmin(db);
   const userId = adminUser.id;
 
   let pagesCreated = 0;
   for (const page of DEMO_PAGES) {
-    await db.document.create({
-      data: {
-        collection: "pages",
-        data: page,
-        status: "PUBLISHED",
-        publishedAt: new Date(),
-        createdById: userId,
-        updatedById: userId,
-        plainText: `${page.title} ${page.slug}`,
-      },
+    await createSeedDocument(db, userId, {
+      collection: "pages",
+      data: page,
+      status: "PUBLISHED",
     });
     pagesCreated++;
   }
 
   let postsCreated = 0;
   for (const post of DEMO_POSTS) {
-    await db.document.create({
-      data: {
-        collection: "posts",
-        data: post,
-        status: post.status,
-        publishedAt: post.status === "PUBLISHED" ? new Date() : null,
-        createdById: userId,
-        updatedById: userId,
-        plainText: `${post.title} ${post.excerpt}`,
-      },
+    await createSeedDocument(db, userId, {
+      collection: "posts",
+      data: post,
+      status: post.status,
     });
     postsCreated++;
   }
 
   let formsCreated = 0;
   for (const form of DEMO_FORMS) {
-    await db.document.create({
-      data: {
-        collection: "forms",
-        data: form,
-        status: "PUBLISHED",
-        publishedAt: new Date(),
-        createdById: userId,
-        updatedById: userId,
-        plainText: `${form.title} ${form.slug}`,
-      },
+    await createSeedDocument(db, userId, {
+      collection: "forms",
+      data: form,
+      status: "PUBLISHED",
     });
     formsCreated++;
   }
@@ -426,56 +531,16 @@ async function seedFromFile(db: any, filePath: string): Promise<void> {
     process.exit(1);
   }
 
-  let adminUser = await db.user.findFirst({ where: { role: "ADMIN" } });
-  if (!adminUser) {
-    adminUser = await db.user.create({
-      data: {
-        email: "admin@actuatecms.dev",
-        name: "Admin",
-        role: "ADMIN",
-        isActive: true,
-        isApproved: true,
-        emailVerified: true,
-      },
-    });
-  }
+  const adminUser = await ensureSeedAdmin(db);
   const userId = adminUser.id;
 
   const normalized = normalizeSeedPayload(seedData);
-  const { extractPlainText, hashContent, updateGlobal } = await import("@actuate-media/cms-core");
+  const { updateGlobal } = await import("@actuate-media/cms-core");
   const ctx = { userId, role: "ADMIN", db };
 
   let documentCount = 0;
   for (const doc of normalized.documents) {
-    const serialized = JSON.stringify(doc.data);
-    const plainText = extractPlainText(serialized);
-    const contentHash = await hashContent(serialized);
-
-    await db.$transaction(async (tx: any) => {
-      const created = await tx.document.create({
-        data: {
-          collection: doc.collection,
-          title: typeof doc.data.title === "string" ? doc.data.title : null,
-          slug: typeof doc.data.slug === "string" ? doc.data.slug : null,
-          data: doc.data,
-          status: doc.status,
-          publishedAt: doc.status === "PUBLISHED" ? new Date() : null,
-          createdById: userId,
-          updatedById: userId,
-          plainText,
-          contentHash,
-        },
-      });
-
-      await tx.version.create({
-        data: {
-          documentId: created.id,
-          data: doc.data,
-          changedById: userId,
-          changeType: "CREATE",
-        },
-      });
-    });
+    await createSeedDocument(db, userId, doc);
     documentCount++;
   }
 

package/src/deployment/diagnostics.ts

@@ -0,0 +1,189 @@
+export type DiagnosticStatus = 'pass' | 'warn' | 'fail';
+
+export interface DiagnosticCheck {
+  id: string;
+  label: string;
+  status: DiagnosticStatus;
+  message: string;
+  fix?: string;
+  docs?: string;
+}
+
+export interface DiagnosticReport {
+  status: DiagnosticStatus;
+  checks: DiagnosticCheck[];
+}
+
+export const REQUIRED_CMS_MODELS = [
+  'User',
+  'Session',
+  'Document',
+  'Media',
+  'Version',
+  'Folder',
+  'Redirect',
+  'FormSubmission',
+  'AuditLog',
+  'PasswordResetToken',
+  'MediaUsage',
+  'ScriptTag',
+  'PageTemplate',
+  'SavedSection',
+] as const;
+
+export const REQUIRED_ENV_VARS = [
+  'DATABASE_URL',
+  'CMS_SECRET',
+  'CMS_ENCRYPTION_KEY',
+  'NEXT_PUBLIC_SITE_URL',
+] as const;
+
+export interface DiagnosticInput {
+  schemaModels: Set<string>;
+  schemaContent?: string;
+  env: Record<string, string | undefined>;
+  packageManager: string;
+  schemaPath: string;
+  mode?: 'doctor' | 'deploy';
+}
+
+export function missingModels(schemaModels: Set<string>): string[] {
+  return REQUIRED_CMS_MODELS.filter((model) => !schemaModels.has(model));
+}
+
+export function missingEnvVars(env: Record<string, string | undefined>): string[] {
+  return REQUIRED_ENV_VARS.filter((name) => !env[name]);
+}
+
+export function detectPackageManager(lockfiles: Set<string>): string {
+  if (lockfiles.has('pnpm-lock.yaml')) return 'pnpm';
+  if (lockfiles.has('yarn.lock')) return 'yarn';
+  if (lockfiles.has('package-lock.json')) return 'npm';
+  return 'npm';
+}
+
+export function createDiagnosticReport(input: DiagnosticInput): DiagnosticReport {
+  const checks: DiagnosticCheck[] = [];
+  const models = missingModels(input.schemaModels);
+  const envVars = input.mode === 'deploy'
+    ? [...missingEnvVars(input.env), ...(!input.env.DIRECT_DATABASE_URL ? ['DIRECT_DATABASE_URL'] : [])]
+    : missingEnvVars(input.env);
+  const fieldProblems = input.schemaContent ? missingCriticalFields(input.schemaContent) : [];
+
+  checks.push({
+    id: 'schema-models',
+    label: 'Prisma schema models',
+    status: models.length === 0 ? 'pass' : 'fail',
+    message: models.length === 0
+      ? 'All deploy-critical Actuate models are present.'
+      : `Missing deploy-critical Actuate models: ${models.join(', ')}.`,
+    fix: models.length === 0
+      ? undefined
+      : `Run \`actuate db:init --schema ${input.schemaPath}\` for new schemas, or update the existing Actuate block from the database setup docs, then create and apply a Prisma migration.`,
+    docs: 'https://actuatecms.dev/docs/database-setup',
+  });
+
+  checks.push({
+    id: 'schema-fields',
+    label: 'Prisma schema fields',
+    status: fieldProblems.length === 0 ? 'pass' : 'fail',
+    message: fieldProblems.length === 0
+      ? 'Deploy-critical model fields are present.'
+      : `Missing deploy-critical model fields: ${fieldProblems.join(', ')}.`,
+    fix: fieldProblems.length === 0
+      ? undefined
+      : 'Update the Actuate Prisma models from the database setup docs, then create and apply a Prisma migration.',
+    docs: 'https://actuatecms.dev/docs/database-setup',
+  });
+
+  checks.push({
+    id: 'environment',
+    label: 'Required environment variables',
+    status: envVars.length === 0 ? 'pass' : 'fail',
+    message: envVars.length === 0
+      ? 'Required deployment environment variables are set.'
+      : `Missing required environment variables: ${envVars.join(', ')}.`,
+    fix: envVars.length === 0
+      ? undefined
+      : `Set missing environment variables before deploying: ${envVars.join(', ')}.`,
+    docs: 'https://actuatecms.dev/docs/environment-variables',
+  });
+
+  checks.push({
+    id: 'package-manager',
+    label: 'Package manager',
+    status: 'pass',
+    message: `Detected ${input.packageManager}. Use the same package manager for install, build, and deploy checks.`,
+  });
+
+  const status: DiagnosticStatus = checks.some((check) => check.status === 'fail')
+    ? 'fail'
+    : checks.some((check) => check.status === 'warn')
+    ? 'warn'
+    : 'pass';
+
+  return { status, checks };
+}
+
+export function buildDeploymentManifest() {
+  return {
+    schemaVersion: 1,
+    packageScope: '@actuate-media',
+    registry: 'https://registry.npmjs.org',
+    requiredModels: [...REQUIRED_CMS_MODELS],
+    requiredEnv: [...REQUIRED_ENV_VARS],
+    optionalEnv: [
+      'DIRECT_DATABASE_URL',
+      'CMS_ADMIN_EMAIL',
+      'CMS_ADMIN_PASSWORD',
+      'BLOB_READ_WRITE_TOKEN',
+      'UPSTASH_REDIS_REST_URL',
+      'UPSTASH_REDIS_REST_TOKEN',
+      'RESEND_API_KEY',
+    ],
+    routes: {
+      apiHealth: '/api/cms/health',
+      apiBase: '/api/cms',
+      adminDefault: '/admin',
+    },
+    crons: {
+      scheduledPublish: '/api/cms/cron/publish',
+      cleanup: '/api/cms/cron/cleanup',
+      seoScan: '/api/cms/cron/seo-scan',
+    },
+    verification: {
+      preflight: 'actuate doctor',
+      production: 'actuate deploy:check',
+      postDeploy: 'actuate verify --full',
+    },
+    docs: {
+      deployment: 'https://actuatecms.dev/docs/deployment',
+      databaseSetup: 'https://actuatecms.dev/docs/database-setup',
+      environmentVariables: 'https://actuatecms.dev/docs/environment-variables',
+      aiRunbook: 'https://actuatecms.dev/docs/ai-runbook',
+    },
+  };
+}
+
+export function missingCriticalFields(schemaContent: string): string[] {
+  const requiredFields: Record<string, string[]> = {
+    ScriptTag: ['targetPaths', 'priority', 'enabled'],
+    PageTemplate: ['tree', 'builtIn', 'category'],
+    SavedSection: ['tree', 'usageCount', 'category'],
+    PasswordResetToken: ['tokenHash', 'expiresAt', 'usedAt'],
+    MediaUsage: ['mediaId', 'documentId', 'fieldPath'],
+  };
+  const missing: string[] = [];
+
+  for (const [model, fields] of Object.entries(requiredFields)) {
+    const body = schemaContent.match(new RegExp(`model\\s+${model}\\s+\\{([\\s\\S]*?)\\n\\}`))?.[1] ?? '';
+    if (!body) continue;
+    for (const field of fields) {
+      if (!new RegExp(`^\\s*${field}\\s+`, 'm').test(body)) {
+        missing.push(`${model}.${field}`);
+      }
+    }
+  }
+
+  return missing;
+}

package/src/index.ts

@@ -10,6 +10,11 @@ import { registerUpdateCheckCommand } from "./commands/update-check.js";
 import { registerDbInitCommand } from "./commands/db-init.js";
 import { registerDbStatusCommand } from "./commands/db-status.js";
 import { registerInitCommand } from "./commands/init.js";
+import {
+  registerDeployCheckCommand,
+  registerDoctorCommand,
+  registerVerifyCommand,
+} from "./commands/doctor.js";
 
 const program = new Command();
 
@@ -28,5 +33,8 @@ registerUpdateCheckCommand(program);
 registerDbInitCommand(program);
 registerDbStatusCommand(program);
 registerInitCommand(program);
+registerDoctorCommand(program);
+registerDeployCheckCommand(program);
+registerVerifyCommand(program);
 
 program.parse();