@actuate-media/cli 0.3.1 → 0.4.1

package/src/commands/db-init.ts

@@ -7,6 +7,20 @@ import { logger } from "../utils/logger.js";
 
 const CMS_SCHEMA_MARKER = "// ── Actuate CMS models";
 
+export let runDbInitCommand = (command: string, options: ExecSyncOptions): void => {
+  execSync(command, options);
+};
+
+const defaultDbInitCommandRunner = runDbInitCommand;
+
+export function setDbInitCommandRunner(runner: typeof runDbInitCommand): void {
+  runDbInitCommand = runner;
+}
+
+export function resetDbInitCommandRunner(): void {
+  runDbInitCommand = defaultDbInitCommandRunner;
+}
+
 async function fileExists(filePath: string): Promise<boolean> {
   try {
     await access(filePath);
@@ -219,6 +233,75 @@ model AuditLog {
   @@index([userId])
   @@index([createdAt])
 }
+
+model PasswordResetToken {
+  id        String    @id @default(cuid())
+  userId    String
+  tokenHash String
+  expiresAt DateTime
+  usedAt    DateTime?
+  createdAt DateTime  @default(now())
+
+  @@index([tokenHash])
+  @@index([userId])
+}
+
+model MediaUsage {
+  id          String   @id @default(cuid())
+  mediaId     String
+  documentId  String
+  fieldPath   String?
+  createdAt   DateTime @default(now())
+
+  @@unique([mediaId, documentId, fieldPath])
+  @@index([mediaId])
+  @@index([documentId])
+}
+
+model ScriptTag {
+  id          String   @id @default(cuid())
+  name        String
+  code        String   @db.Text
+  placement   String
+  scope       String
+  targetPaths String[]
+  priority    Int      @default(100)
+  enabled     Boolean  @default(true)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([enabled])
+  @@index([placement])
+}
+
+model PageTemplate {
+  id          String   @id @default(cuid())
+  name        String
+  description String?
+  category    String   @default("content")
+  tree        Json
+  thumbnail   String?
+  builtIn     Boolean  @default(false)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([category])
+  @@index([builtIn])
+}
+
+model SavedSection {
+  id          String   @id @default(cuid())
+  name        String
+  description String?
+  category    String   @default("content")
+  tree        Json
+  thumbnail   String?
+  usageCount  Int      @default(0)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([category])
+}
 `;
 }
 
@@ -279,7 +362,7 @@ export function registerDbInitCommand(program: Command): void {
       const genSpinner = ora("Running prisma generate...").start();
       try {
         genSpinner.stop();
-        execSync("npx prisma generate", execOpts);
+        runDbInitCommand("npx prisma generate", execOpts);
         logger.success("Prisma client generated.");
       } catch {
         logger.warn("prisma generate failed. You may need to set DATABASE_URL first.");
@@ -289,7 +372,7 @@ export function registerDbInitCommand(program: Command): void {
         const migSpinner = ora("Running prisma migrate dev...").start();
         try {
           migSpinner.stop();
-          execSync("npx prisma migrate dev --name actuate-cms-init", execOpts);
+          runDbInitCommand("npx prisma migrate dev --name actuate-cms-init", execOpts);
           logger.success("Migration created and applied.");
         } catch {
           logger.warn("prisma migrate dev failed. Run it manually after setting DATABASE_URL.");

package/src/commands/db-status.ts

@@ -5,18 +5,7 @@ import { resolve } from "node:path";
 import ora from "ora";
 import chalk from "chalk";
 import { logger } from "../utils/logger.js";
-
-const CMS_EXPECTED_MODELS = [
-  "User",
-  "Session",
-  "Document",
-  "Media",
-  "Version",
-  "Folder",
-  "Redirect",
-  "FormSubmission",
-  "AuditLog",
-];
+import { REQUIRED_CMS_MODELS } from "../deployment/diagnostics.js";
 
 const CMS_SCHEMA_MARKER = "// ── Actuate CMS models";
 
@@ -74,7 +63,7 @@ export function registerDbStatusCommand(program: Command): void {
       let present = 0;
       let missing = 0;
 
-      for (const model of CMS_EXPECTED_MODELS) {
+      for (const model of REQUIRED_CMS_MODELS) {
         if (schemaModels.has(model)) {
           console.log(`  ${chalk.green("✓")} ${model}`);
           present++;

package/src/commands/doctor.ts

@@ -0,0 +1,169 @@
+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 readOptionalFile(path: string): Promise<string> {
+  if (!(await fileExists(path))) return "";
+  return readFile(path, "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, configPath: string, mode: "doctor" | "deploy" = "doctor") {
+  const resolvedSchema = resolve(process.cwd(), schemaPath);
+  const resolvedConfig = resolve(process.cwd(), configPath);
+  const [schemaModels, schemaContent, configContent, packageManager] = await Promise.all([
+    readSchemaModels(resolvedSchema),
+    readSchemaContent(resolvedSchema),
+    readOptionalFile(resolvedConfig),
+    detectProjectPackageManager(),
+  ]);
+
+  return createDiagnosticReport({
+    schemaModels,
+    schemaContent,
+    configContent,
+    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("--config <path>", "Path to actuate.config.ts", "actuate.config.ts")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (opts: { schema: string; config: string; json?: boolean }) => {
+      const report = await buildReport(opts.schema, opts.config, "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("--config <path>", "Path to actuate.config.ts", "actuate.config.ts")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (opts: { schema: string; config: string; json?: boolean }) => {
+      const report = await buildReport(opts.schema, opts.config, "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,238 @@
+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;
+  configContent?: 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) : [];
+  const pageBuilderRisk = input.configContent ? detectsFlatMarketingPageModel(input.configContent) : false;
+
+  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.`,
+  });
+
+  checks.push({
+    id: 'design-first-page-builder',
+    label: 'Design-first page builder fit',
+    status: pageBuilderRisk ? 'warn' : 'pass',
+    message: pageBuilderRisk
+      ? 'A pages collection appears to model a designed marketing page as flat hero/body/CTA fields. For marketing, service, location, landing, and homepage routes, prefer a page-builder template with blocks, saved sections, forms, media, and seeded layout content unless field-mapped mode was explicitly approved.'
+      : 'No obvious flat marketing-page model detected in the Actuate config.',
+    fix: pageBuilderRisk
+      ? 'Create a design inventory and block coverage plan, then model section-based pages with page-builder content or document why field-mapped mode is intentional.'
+      : undefined,
+    docs: pageBuilderRisk ? 'https://actuatecms.dev/docs/design-first-page-builder' : undefined,
+  });
+
+  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;
+}
+
+export function detectsFlatMarketingPageModel(configContent: string): boolean {
+  const normalized = configContent.toLowerCase();
+  const hasPagesCollection = /\bpages\b/.test(normalized) || /slug\s*:\s*['"]pages['"]/.test(normalized);
+  if (!hasPagesCollection) return false;
+
+  const hasPageBuilderSignals = [
+    'pagebuilder',
+    'page-builder',
+    "type: 'blocks'",
+    'type: "blocks"',
+    'layout:',
+    'savedsections',
+    'pagetemplate',
+  ].some((signal) => normalized.includes(signal.toLowerCase()));
+
+  if (hasPageBuilderSignals) return false;
+
+  const flatMarketingSignals = [
+    'heroheadline',
+    'herosubheadline',
+    'herotitle',
+    'heroimage',
+    'bodycontent',
+    'ctabuttontext',
+    'ctabuttonurl',
+    'servicecards',
+    'testimonial',
+    'reviews',
+  ];
+
+  const signalCount = flatMarketingSignals.filter((signal) => normalized.includes(signal)).length;
+  return signalCount >= 3;
+}

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