@actuate-media/cli 0.3.1 → 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

@@ -298,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.");
     }

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();