@cms-lab/cli 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afaq Rashid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# cms-lab
+
+CLI for catching CMS-driven Next.js failures before deploy.
+
+```sh
+npx @cms-lab/cli scan
+```
+
+## Commands
+
+```sh
+cms-lab init
+cms-lab doctor
+cms-lab doctor --debug --verbose 2
+cms-lab scan --report
+cms-lab scan --markdown
+cms-lab scan --junit
+cms-lab scan --slack-webhook "$CMS_LAB_SLACK_WEBHOOK"
+cms-lab scan --debug
+cms-lab scan --json
+cms-lab scan --json --include-sensitive-output
+cms-lab scan --max-warnings 0
+cms-lab scan --strict
+cms-lab explain CMS-ROUTE-404
+```
+
+## Scope
+
+cms-lab supports Next.js App Router projects using Prismic, Strapi, Directus,
+and WordPress. It validates configured CMS route mappings, route reachability,
+UID gaps, SEO metadata, image alt text, and project-specific required fields.
+
+Debug logs use stderr and support `--debug` plus `--verbose <0|1|2|3>`, so JSON
+scan output remains clean on stdout. Raw CMS document `data` is redacted from
+`--json` output, along with document URLs, UIDs, and absolute project paths,
+unless `--include-sensitive-output` is passed explicitly.
+
+CI strictness can be raised with `--fail-on warning`, `--max-warnings <count>`,
+`--max-info <count>`, or `--strict`.
+
+Exports include local HTML (`--report`), Markdown (`--markdown`), JUnit XML
+(`--junit`), and redacted Slack incoming webhook summaries
+(`--slack-webhook <url>`). Slack notifications send counts and diagnostic codes
+only, never raw CMS payloads, local paths, or webhook URLs.
+
+## Config
+
+Create `cms-lab.config.ts` in the target Next.js project. Import
+`defineConfig` from `@cms-lab/core`.
+
+See the repository README for full setup, CI, and live Prismic testing.
+
+## Open Source
+
+MIT licensed. See the repository [license](https://github.com/i-afaqrashid/cms-lab/blob/main/LICENSE), [contributing guide](https://github.com/i-afaqrashid/cms-lab/blob/main/CONTRIBUTING.md), and [support guide](https://github.com/i-afaqrashid/cms-lab/blob/main/SUPPORT.md).

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import {
+  runCli
+} from "./chunk-JHH7PD4C.js";
+
+// src/bin.ts
+var exitCode = await runCli(process.argv.slice(2));
+process.exitCode = exitCode;

package/dist/chunk-JHH7PD4C.js

@@ -0,0 +1,1134 @@
+// src/index.ts
+import { Command, CommanderError } from "commander";
+import { access, mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { performance } from "perf_hooks";
+import {
+  CmsFetchError,
+  ConfigLoadError,
+  SiteUnreachableError,
+  explainDiagnostic,
+  loadCmsLabConfig,
+  scanDocuments
+} from "@cms-lab/core";
+import { fetchDirectusDocuments as defaultFetchDirectusDocuments } from "@cms-lab/directus";
+import { detectNextProject } from "@cms-lab/next";
+import { fetchPrismicDocuments as defaultFetchPrismicDocuments } from "@cms-lab/prismic";
+import { renderHtmlReport } from "@cms-lab/reporter";
+import { fetchStrapiDocuments as defaultFetchStrapiDocuments } from "@cms-lab/strapi";
+import { fetchWordPressDocuments as defaultFetchWordPressDocuments } from "@cms-lab/wordpress";
+
+// src/exporters.ts
+function renderMarkdownSummary(result, status) {
+  const lines = [
+    `# cms-lab scan ${status}`,
+    "",
+    "| Errors | Warnings | Info | Documents |",
+    "| ---: | ---: | ---: | ---: |",
+    `| ${result.summary.errors} | ${result.summary.warnings} | ${result.summary.info} | ${result.documents.length} |`,
+    ""
+  ];
+  if (result.diagnostics.length === 0) {
+    lines.push("No diagnostics found.", "");
+    return lines.join("\n");
+  }
+  lines.push("## Diagnostics", "");
+  lines.push("| Severity | Code | Message | Source |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const diagnostic of result.diagnostics) {
+    lines.push(
+      `| ${escapeMarkdown(diagnostic.severity)} | ${escapeMarkdown(diagnostic.code)} | ${escapeMarkdown(diagnostic.message)} | ${escapeMarkdown(diagnostic.source ?? "")} |`
+    );
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderJUnitReport(result) {
+  const diagnostics = result.diagnostics.length > 0 ? result.diagnostics : [
+    {
+      severity: "info",
+      code: "CMS-LAB-PASS",
+      message: "cms-lab scan passed with no diagnostics"
+    }
+  ];
+  const failures = result.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "error"
+  );
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuite name="cms-lab" tests="${diagnostics.length}" failures="${failures.length}" errors="0">`,
+    ...diagnostics.map((diagnostic) => renderJUnitTestcase(diagnostic)),
+    "</testsuite>",
+    ""
+  ].join("\n");
+}
+function renderSlackPayload(result, status) {
+  const summary = `${result.summary.errors} ${plural(result.summary.errors, "error")}, ${result.summary.warnings} ${plural(result.summary.warnings, "warning")}, ${result.summary.info} ${plural(result.summary.info, "info item")}, ${result.documents.length} ${plural(result.documents.length, "document")}`;
+  const codes = [
+    ...new Set(result.diagnostics.map((diagnostic) => diagnostic.code))
+  ].slice(0, 5).join(", ");
+  const suffix = codes ? ` Top codes: ${codes}.` : "";
+  return {
+    text: `cms-lab scan ${status}: ${summary}.${suffix}`
+  };
+}
+async function postSlackPayload(options) {
+  const response = await (options.fetchImpl ?? fetch)(options.webhookUrl, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(options.payload)
+  });
+  if (!response.ok) {
+    throw new Error(`Slack webhook returned HTTP ${response.status}`);
+  }
+}
+function renderJUnitTestcase(diagnostic) {
+  const classname = `cms-lab.${groupForDiagnostic(diagnostic)}`;
+  const name = diagnostic.code;
+  if (diagnostic.severity === "error") {
+    return `  <testcase classname="${escapeXml(classname)}" name="${escapeXml(name)}"><failure message="${escapeXml(diagnostic.message)}">${escapeXml(diagnostic.message)}</failure></testcase>`;
+  }
+  return `  <testcase classname="${escapeXml(classname)}" name="${escapeXml(name)}"><system-out>${escapeXml(diagnostic.message)}</system-out></testcase>`;
+}
+function groupForDiagnostic(diagnostic) {
+  if (diagnostic.code.startsWith("CMS-ROUTE") || diagnostic.code === "CMS-UID-MISSING") {
+    return "routes";
+  }
+  if (diagnostic.code.startsWith("CMS-FIELD")) {
+    return "fields";
+  }
+  if (diagnostic.code.startsWith("SEO-")) {
+    return "seo";
+  }
+  if (diagnostic.code.startsWith("A11Y-")) {
+    return "a11y";
+  }
+  return "other";
+}
+function escapeMarkdown(value) {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function plural(value, singular) {
+  return value === 1 ? singular : `${singular}s`;
+}
+
+// src/output.ts
+import pc from "picocolors";
+function formatPrettyResult(result, options = {}) {
+  const color = options.color ?? false;
+  const paint = color ? pc : noColor;
+  const failOn = options.failOn ?? "error";
+  const thresholdFailure = thresholdFailureMessage(result, options);
+  const lines = [];
+  lines.push(paint.bold("cms-lab"));
+  lines.push(`project ${result.project.framework} ${result.project.router}`);
+  lines.push(`documents ${result.documents.length}`);
+  lines.push("");
+  appendGroup(
+    lines,
+    "errors",
+    result.diagnostics.filter((diagnostic) => diagnostic.severity === "error"),
+    paint.red
+  );
+  appendGroup(
+    lines,
+    "warnings",
+    result.diagnostics.filter(
+      (diagnostic) => diagnostic.severity === "warning"
+    ),
+    paint.yellow
+  );
+  appendGroup(
+    lines,
+    "info",
+    result.diagnostics.filter((diagnostic) => diagnostic.severity === "info"),
+    paint.cyan
+  );
+  lines.push("");
+  lines.push("summary");
+  lines.push(`  errors   ${result.summary.errors}`);
+  lines.push(`  warnings ${result.summary.warnings}`);
+  lines.push(`  info     ${result.summary.info}`);
+  lines.push("");
+  if (result.summary.errors > 0 && failOn !== "never") {
+    lines.push(
+      paint.red(
+        `scan failed - ${result.summary.errors} ${plural2(result.summary.errors, "error")}`
+      )
+    );
+  } else if (failOn === "warning" && result.summary.warnings > 0) {
+    lines.push(
+      paint.yellow(
+        `scan failed - ${result.summary.warnings} ${plural2(result.summary.warnings, "warning")}`
+      )
+    );
+  } else if (thresholdFailure) {
+    lines.push(paint.red(thresholdFailure));
+  } else if (failOn === "never" && (result.summary.errors > 0 || result.summary.warnings > 0)) {
+    lines.push(
+      paint.cyan("scan completed - diagnostics ignored by --fail-on never")
+    );
+  } else {
+    lines.push(paint.green("scan passed"));
+  }
+  if (options.hints && result.diagnostics.length > 0) {
+    lines.push("");
+    lines.push("next");
+    lines.push(`  cms-lab explain ${result.diagnostics[0].code}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function thresholdFailureMessage(result, options) {
+  if (options.maxWarnings !== void 0 && result.summary.warnings > options.maxWarnings) {
+    return `scan failed - ${result.summary.warnings} ${plural2(result.summary.warnings, "warning")} exceed --max-warnings ${options.maxWarnings}`;
+  }
+  if (options.maxInfo !== void 0 && result.summary.info > options.maxInfo) {
+    return `scan failed - ${result.summary.info} ${plural2(result.summary.info, "info item")} exceed --max-info ${options.maxInfo}`;
+  }
+  return void 0;
+}
+function appendGroup(lines, title, diagnostics, color) {
+  if (diagnostics.length === 0) {
+    return;
+  }
+  lines.push(title);
+  for (const diagnostic of diagnostics) {
+    const location = diagnostic.path ? ` ${diagnostic.path}` : "";
+    const source = diagnostic.source ? ` (${diagnostic.source})` : "";
+    lines.push(
+      `  ${color(diagnostic.code)}${location} - ${diagnostic.message}${source}`
+    );
+  }
+  lines.push("");
+}
+function plural2(value, singular) {
+  return value === 1 ? singular : `${singular}s`;
+}
+var noColor = {
+  bold: (value) => value,
+  red: (value) => value,
+  yellow: (value) => value,
+  cyan: (value) => value,
+  green: (value) => value
+};
+
+// src/index.ts
+async function runCli(argv, dependencies = {}) {
+  let exitCode = 0;
+  const program = new Command().name("cms-lab").description("Catch CMS bugs before deploy.").version("1.0.1").exitOverride().configureOutput({
+    writeOut: (text) => writeStdout(dependencies, text),
+    writeErr: (text) => writeStderr(dependencies, text)
+  });
+  program.addHelpText(
+    "after",
+    `
+Examples:
+  cms-lab init
+  cms-lab doctor --config cms-lab.config.ts
+  cms-lab scan --ci --report
+  cms-lab explain CMS-ROUTE-404
+`
+  );
+  program.command("scan").description("Scan CMS content against configured site routes.").option("--url <url>", "Override config.site.url").option("--config <path>", "Path to cms-lab config file").option("--json", "Print ScanResult JSON").option("--ci", "Use stable CI-friendly terminal output").option(
+    "--fail-on <level>",
+    "Exit with code 1 on error, warning, or never",
+    "error"
+  ).option(
+    "--max-warnings <count>",
+    "Exit with code 1 when warnings exceed this count"
+  ).option(
+    "--max-info <count>",
+    "Exit with code 1 when info diagnostics exceed this count"
+  ).option(
+    "--strict",
+    "Fail on warnings and info diagnostics. Equivalent to --fail-on warning --max-info 0."
+  ).option(
+    "--report [path]",
+    "Write an HTML report. Defaults to .cms-lab/report.html"
+  ).option(
+    "--markdown [path]",
+    "Write a Markdown summary. Defaults to .cms-lab/summary.md"
+  ).option(
+    "--junit [path]",
+    "Write a JUnit XML report. Defaults to .cms-lab/junit.xml"
+  ).option(
+    "--slack-webhook <url>",
+    "Post a redacted scan summary to a Slack incoming webhook"
+  ).option(
+    "--notify-on <mode>",
+    "When to notify Slack: always, failure, or diagnostics",
+    "failure"
+  ).option(
+    "--include-sensitive-output",
+    "Include raw CMS document data and local project paths in --json output"
+  ).option(
+    "--type <type>",
+    "Limit scan to a CMS content type. Repeatable; comma-separated values are allowed.",
+    collectOption,
+    []
+  ).option(
+    "--only <check>",
+    "Run only a check group. Repeatable; comma-separated values are allowed.",
+    collectOption,
+    []
+  ).option(
+    "--skip <check>",
+    "Skip a check group. Repeatable; comma-separated values are allowed.",
+    collectOption,
+    []
+  ).option("--timeout <ms>", "Per-route HTTP timeout in milliseconds").option("--concurrency <count>", "Maximum concurrent route probes").option("--retries <count>", "Retry transient route probe failures", "1").option("--debug", "Write debug logs to stderr").option("--verbose <level>", "Debug verbosity level: 0, 1, 2, or 3").option("--no-color", "Disable ANSI color in terminal output").addHelpText(
+    "after",
+    `
+Examples:
+  cms-lab scan
+  cms-lab scan --url https://staging.example.com
+  cms-lab scan --ci --report
+  cms-lab scan --json --include-sensitive-output
+  cms-lab scan --only routes,fields --fail-on warning
+`
+  ).action(async (options) => {
+    exitCode = await runScan(options, dependencies);
+  });
+  program.command("doctor").description(
+    "Validate cms-lab config, project, site, and CMS connectivity."
+  ).option("--url <url>", "Override config.site.url").option("--config <path>", "Path to cms-lab config file").option("--timeout <ms>", "HTTP timeout in milliseconds").option("--retries <count>", "Retry transient connectivity failures", "1").option("--debug", "Write debug logs to stderr").option("--verbose <level>", "Debug verbosity level: 0, 1, 2, or 3").addHelpText(
+    "after",
+    `
+Examples:
+  cms-lab doctor
+  cms-lab doctor --config cms-lab.config.ts
+  cms-lab doctor --url https://staging.example.com --debug
+`
+  ).action(async (options) => {
+    exitCode = await runDoctor(options, dependencies);
+  });
+  program.command("explain").argument("<code>", "Diagnostic code to explain").description("Explain a cms-lab diagnostic code.").addHelpText(
+    "after",
+    `
+Examples:
+  cms-lab explain CMS-ROUTE-404
+  cms-lab explain SEO-META-MISSING
+`
+  ).action((code) => {
+    exitCode = runExplain(code, dependencies);
+  });
+  program.command("init").description("Create a starter cms-lab.config.ts file.").option("--config <path>", "Config file path", "cms-lab.config.ts").option("--force", "Overwrite an existing config file").option("--repository <name>", "Prismic repository name", "my-repo").option("--url <url>", "Site URL", "http://localhost:3000").addHelpText(
+    "after",
+    `
+Examples:
+  cms-lab init
+  cms-lab init --repository my-prismic-repo --url http://localhost:3000
+  cms-lab init --config cms-lab.config.ts --force
+`
+  ).action(async (options) => {
+    exitCode = await runInit(options, dependencies);
+  });
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return exitCode;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      return error.exitCode ?? 2;
+    }
+    writeStderr(dependencies, `Unexpected error: ${messageFrom(error)}
+`);
+    return 2;
+  }
+}
+async function runScan(options, dependencies) {
+  const cwd = dependencies.cwd ?? process.cwd();
+  let debug = createNoopDebugLogger();
+  let endTotal = () => {
+  };
+  try {
+    debug = createDebugLogger(
+      "scan",
+      options.debug,
+      options.verbose,
+      dependencies
+    );
+    endTotal = debug.time("total", 2);
+    const timeoutMs = parseTimeout(options.timeout);
+    const concurrency = parseConcurrency(options.concurrency);
+    const retries = parseRetries(options.retries);
+    const strict = Boolean(options.strict);
+    const failOn = strict ? "warning" : parseFailOn(options.failOn);
+    const maxWarnings = parseOptionalThreshold(
+      options.maxWarnings,
+      "--max-warnings"
+    );
+    const maxInfo = parseOptionalThreshold(
+      options.maxInfo ?? (strict ? "0" : void 0),
+      "--max-info"
+    );
+    const notifyOn = parseNotifyOn(options.notifyOn);
+    const filters = {
+      types: splitList(options.type),
+      only: parseCheckGroups(options.only),
+      skip: parseCheckGroups(options.skip)
+    };
+    debug.log(1, `cwd ${cwd}`);
+    debug.log(
+      2,
+      `options ${describeScanOptions(
+        { ...options, failOn, maxWarnings, maxInfo },
+        filters
+      )}`
+    );
+    const endConfig = debug.time("config", 2);
+    const loaded = await loadCmsLabConfig({ cwd, configPath: options.config });
+    endConfig();
+    const config = {
+      ...loaded.config,
+      site: {
+        ...loaded.config.site,
+        url: options.url ?? loaded.config.site.url
+      }
+    };
+    debug.log(1, `config ${loaded.configFile ?? "inline"}`);
+    debug.log(1, `site ${config.site.url}`);
+    debug.log(1, `cms ${describeCms(config.cms)}`);
+    if (config.framework.router !== "app") {
+      throw new ConfigLoadError(
+        "cms-lab only supports Next.js App Router projects"
+      );
+    }
+    const endProject = debug.time("project detection", 2);
+    const project = await detectNextProject(cwd);
+    endProject();
+    if (project.router !== "app") {
+      throw new ConfigLoadError(
+        "cms-lab only supports Next.js App Router projects"
+      );
+    }
+    debug.log(
+      1,
+      `project next ${project.router} appDir=${project.appDir ?? "none"}`
+    );
+    const endCms = debug.time("cms fetch", 2);
+    const documents = await fetchCmsDocuments(config.cms, dependencies);
+    endCms();
+    debug.log(1, `documents ${documents.length}`);
+    debug.log(3, `document types ${describeDocumentTypes(documents)}`);
+    assertTypeFilterMatched(documents, filters.types);
+    const endScan = debug.time("scan", 2);
+    const result = await scanDocuments({
+      config,
+      project,
+      documents,
+      fetch: dependencies.fetch,
+      timeoutMs,
+      concurrency,
+      retries,
+      filters
+    });
+    endScan();
+    debug.log(
+      1,
+      `summary errors=${result.summary.errors} warnings=${result.summary.warnings} info=${result.summary.info}`
+    );
+    const exitCode = exitCodeForResult(result, {
+      failOn,
+      maxWarnings,
+      maxInfo
+    });
+    const status = exitCode === 0 ? "passed" : "failed";
+    const endReport = debug.time("exports", 2);
+    await maybeWriteReport(options.report, result, cwd);
+    await maybeWriteMarkdown(options.markdown, result, status, cwd);
+    await maybeWriteJUnit(options.junit, result, cwd);
+    const slackSent = await maybePostSlack({
+      webhookUrl: options.slackWebhook,
+      notifyOn,
+      result,
+      status,
+      fetchImpl: dependencies.fetch
+    });
+    endReport();
+    if (options.report) {
+      debug.log(1, `report ${reportPathFromOption(options.report, cwd)}`);
+    }
+    if (options.markdown) {
+      debug.log(1, `markdown ${markdownPathFromOption(options.markdown, cwd)}`);
+    }
+    if (options.junit) {
+      debug.log(1, `junit ${junitPathFromOption(options.junit, cwd)}`);
+    }
+    if (slackSent) {
+      debug.log(1, "slack webhook sent");
+    } else if (options.slackWebhook) {
+      debug.log(1, "slack webhook skipped");
+    }
+    if (options.json) {
+      writeStdout(
+        dependencies,
+        `${JSON.stringify(jsonOutputResult(result, options), null, 2)}
+`
+      );
+    } else {
+      writeStdout(
+        dependencies,
+        formatPrettyResult(result, {
+          color: shouldUseColor(options, dependencies),
+          failOn,
+          maxWarnings,
+          maxInfo,
+          hints: !options.ci
+        })
+      );
+      if (options.report) {
+        writeStdout(
+          dependencies,
+          `report ${reportPathFromOption(options.report, cwd)}
+`
+        );
+      }
+      if (options.markdown) {
+        writeStdout(
+          dependencies,
+          `markdown ${markdownPathFromOption(options.markdown, cwd)}
+`
+        );
+      }
+      if (options.junit) {
+        writeStdout(
+          dependencies,
+          `junit ${junitPathFromOption(options.junit, cwd)}
+`
+        );
+      }
+    }
+    endTotal();
+    return exitCode;
+  } catch (error) {
+    endTotal();
+    debug.log(1, `error ${safeMessageFrom(error)}`);
+    if (error instanceof ConfigLoadError) {
+      writeStderr(
+        dependencies,
+        `Config error: ${redactSensitive(error.message)}
+`
+      );
+      return 2;
+    }
+    if (error instanceof CmsFetchError) {
+      writeStderr(
+        dependencies,
+        `CMS error: ${redactSensitive(error.message)}
+`
+      );
+      return 3;
+    }
+    if (error instanceof SiteUnreachableError) {
+      writeStderr(
+        dependencies,
+        `Site error: ${redactSensitive(error.message)}
+`
+      );
+      return 4;
+    }
+    writeStderr(dependencies, `Unexpected error: ${safeMessageFrom(error)}
+`);
+    return 2;
+  }
+}
+async function runDoctor(options, dependencies) {
+  const cwd = dependencies.cwd ?? process.cwd();
+  let debug = createNoopDebugLogger();
+  let endTotal = () => {
+  };
+  try {
+    debug = createDebugLogger(
+      "doctor",
+      options.debug,
+      options.verbose,
+      dependencies
+    );
+    endTotal = debug.time("total", 2);
+    const timeoutMs = parseTimeout(options.timeout) ?? 5e3;
+    const retries = parseRetries(options.retries) ?? 1;
+    debug.log(1, `cwd ${cwd}`);
+    debug.log(
+      2,
+      `options timeout=${timeoutMs} retries=${retries} url=${options.url ?? "config"}`
+    );
+    const endConfig = debug.time("config", 2);
+    const loaded = await loadCmsLabConfig({ cwd, configPath: options.config });
+    endConfig();
+    const config = {
+      ...loaded.config,
+      site: {
+        ...loaded.config.site,
+        url: options.url ?? loaded.config.site.url
+      }
+    };
+    debug.log(1, `config ${loaded.configFile ?? "inline"}`);
+    debug.log(1, `site ${config.site.url}`);
+    debug.log(1, `cms ${describeCms(config.cms)}`);
+    writeStdout(
+      dependencies,
+      `config ok${loaded.configFile ? ` - ${loaded.configFile}` : ""}
+`
+    );
+    if (config.framework.router !== "app") {
+      throw new ConfigLoadError(
+        "cms-lab only supports Next.js App Router projects"
+      );
+    }
+    const endProject = debug.time("project detection", 2);
+    const project = await detectNextProject(cwd);
+    endProject();
+    if (project.router !== "app") {
+      throw new ConfigLoadError(
+        "cms-lab only supports Next.js App Router projects"
+      );
+    }
+    debug.log(
+      1,
+      `project next ${project.router} appDir=${project.appDir ?? "none"}`
+    );
+    writeStdout(
+      dependencies,
+      `next app ok - ${project.appDir ?? project.rootDir}
+`
+    );
+    const endSite = debug.time("site probe", 2);
+    await fetchSite(config.site.url, dependencies.fetch, timeoutMs, retries);
+    endSite();
+    writeStdout(dependencies, `site ok - ${config.site.url}
+`);
+    const endCms = debug.time("cms fetch", 2);
+    const documents = await fetchCmsDocuments(config.cms, dependencies);
+    endCms();
+    debug.log(1, `documents ${documents.length}`);
+    debug.log(3, `document types ${describeDocumentTypes(documents)}`);
+    writeStdout(
+      dependencies,
+      `cms ok - ${documents.length} ${plural3(documents.length, "document")}
+`
+    );
+    endTotal();
+    return 0;
+  } catch (error) {
+    endTotal();
+    debug.log(1, `error ${safeMessageFrom(error)}`);
+    if (error instanceof ConfigLoadError) {
+      writeStderr(
+        dependencies,
+        `Config error: ${redactSensitive(error.message)}
+`
+      );
+      return 2;
+    }
+    if (error instanceof CmsFetchError) {
+      writeStderr(
+        dependencies,
+        `CMS error: ${redactSensitive(error.message)}
+`
+      );
+      return 3;
+    }
+    if (error instanceof SiteUnreachableError) {
+      writeStderr(
+        dependencies,
+        `Site error: ${redactSensitive(error.message)}
+`
+      );
+      return 4;
+    }
+    writeStderr(dependencies, `Unexpected error: ${safeMessageFrom(error)}
+`);
+    return 2;
+  }
+}
+function runExplain(code, dependencies) {
+  const explanation = explainDiagnostic(code);
+  if (!explanation) {
+    writeStderr(dependencies, `Unknown diagnostic code: ${code}
+`);
+    return 2;
+  }
+  writeStdout(
+    dependencies,
+    [
+      `${explanation.code} (${explanation.severity})`,
+      explanation.title,
+      "",
+      `Meaning: ${explanation.meaning}`,
+      `Fix: ${explanation.fix}`,
+      ""
+    ].join("\n")
+  );
+  return 0;
+}
+async function runInit(options, dependencies) {
+  const cwd = dependencies.cwd ?? process.cwd();
+  const target = resolve(cwd, options.config ?? "cms-lab.config.ts");
+  try {
+    if (!options.force && await fileExists(target)) {
+      writeStderr(
+        dependencies,
+        `Config error: ${target} already exists. Use --force to overwrite it.
+`
+      );
+      return 2;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(
+      target,
+      starterConfig({
+        repository: options.repository ?? "my-repo",
+        url: options.url ?? "http://localhost:3000"
+      })
+    );
+    writeStdout(dependencies, `created ${target}
+`);
+    return 0;
+  } catch (error) {
+    writeStderr(dependencies, `Config error: ${messageFrom(error)}
+`);
+    return 2;
+  }
+}
+function writeStdout(dependencies, text) {
+  if (dependencies.stdout) {
+    dependencies.stdout(text);
+    return;
+  }
+  process.stdout.write(text);
+}
+function writeStderr(dependencies, text) {
+  if (dependencies.stderr) {
+    dependencies.stderr(text);
+    return;
+  }
+  process.stderr.write(text);
+}
+function messageFrom(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function safeMessageFrom(error) {
+  return redactSensitive(messageFrom(error));
+}
+function redactSensitive(value) {
+  return value.replaceAll(/(access_token=)[^&\s]+/gi, "$1[redacted]").replaceAll(/([?&](?:token|password|secret)=)[^&\s]+/gi, "$1[redacted]").replaceAll(/\bBearer\s+[-._~+/=a-z0-9]+/gi, "Bearer [redacted]").replaceAll(/(https?:\/\/)([^:\s/@]+):([^@\s/]+)@/gi, "$1[redacted]@");
+}
+function jsonOutputResult(result, options) {
+  if (options.includeSensitiveOutput) {
+    return result;
+  }
+  return {
+    ...result,
+    project: {
+      framework: result.project.framework,
+      router: result.project.router,
+      rootDir: "[redacted: pass --include-sensitive-output to emit raw project paths]",
+      ...result.project.appDir ? {
+        appDir: "[redacted: pass --include-sensitive-output to emit raw project paths]"
+      } : {},
+      ...result.project.pagesDir ? {
+        pagesDir: "[redacted: pass --include-sensitive-output to emit raw project paths]"
+      } : {}
+    },
+    documents: result.documents.map((document) => ({
+      id: document.id,
+      type: document.type,
+      status: document.status,
+      data: "[redacted: pass --include-sensitive-output to emit raw CMS data]"
+    }))
+  };
+}
+function collectOption(value, previous) {
+  return [...previous, value];
+}
+function splitList(values) {
+  return [
+    ...new Set(
+      (values ?? []).flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean)
+    )
+  ];
+}
+function createNoopDebugLogger() {
+  return {
+    log: () => {
+    },
+    time: () => () => {
+    }
+  };
+}
+function createDebugLogger(command, debug, verbose, dependencies) {
+  const level = parseVerbosity(debug, verbose);
+  return {
+    log: (messageLevel, message) => {
+      if (level < messageLevel) {
+        return;
+      }
+      writeStderr(dependencies, `[cms-lab:debug] ${command} ${message}
+`);
+    },
+    time: (label, messageLevel = 2) => {
+      if (level < messageLevel) {
+        return () => {
+        };
+      }
+      const startedAt = performance.now();
+      let ended = false;
+      return () => {
+        if (ended) {
+          return;
+        }
+        ended = true;
+        writeStderr(
+          dependencies,
+          `[cms-lab:debug] ${command} timing ${label} ${formatDuration(
+            performance.now() - startedAt
+          )}
+`
+        );
+      };
+    }
+  };
+}
+function parseVerbosity(debug, verbose) {
+  if (verbose === void 0) {
+    return debug ? 1 : 0;
+  }
+  if (verbose === "0" || verbose === "1" || verbose === "2" || verbose === "3") {
+    return Number(verbose);
+  }
+  throw new ConfigLoadError("--verbose must be one of: 0, 1, 2, 3");
+}
+function shouldUseColor(options, dependencies) {
+  if (options.ci || options.color === false) {
+    return false;
+  }
+  const env = dependencies.env ?? process.env;
+  if (env.NO_COLOR || env.TERM === "dumb") {
+    return false;
+  }
+  return dependencies.isStdoutTTY ?? Boolean(process.stdout.isTTY);
+}
+function describeScanOptions(options, filters) {
+  return [
+    `json=${Boolean(options.json)}`,
+    `ci=${Boolean(options.ci)}`,
+    `report=${Boolean(options.report)}`,
+    `markdown=${Boolean(options.markdown)}`,
+    `junit=${Boolean(options.junit)}`,
+    `slackWebhook=${Boolean(options.slackWebhook)}`,
+    `notifyOn=${options.notifyOn ?? "failure"}`,
+    `failOn=${options.failOn}`,
+    `maxWarnings=${options.maxWarnings ?? "none"}`,
+    `maxInfo=${options.maxInfo ?? "none"}`,
+    `timeout=${options.timeout ?? "default"}`,
+    `concurrency=${options.concurrency ?? "default"}`,
+    `retries=${options.retries ?? "1"}`,
+    `types=${formatList(filters.types)}`,
+    `only=${formatList(filters.only)}`,
+    `skip=${formatList(filters.skip)}`
+  ].join(" ");
+}
+function describeCms(config) {
+  if (config.provider === "prismic") {
+    return `prismic repository=${config.repositoryName}`;
+  }
+  if (config.provider === "strapi") {
+    return `strapi url=${safeUrl(config.url)} collections=${formatList(
+      config.collections.map((collection) => collection.endpoint)
+    )}`;
+  }
+  if (config.provider === "directus") {
+    return `directus url=${safeUrl(config.url)} collections=${formatList(
+      config.collections.map((collection) => collection.collection)
+    )}`;
+  }
+  return `wordpress url=${safeUrl(config.url)} contentTypes=${formatList(
+    config.contentTypes?.map((contentType) => contentType.endpoint) ?? [
+      "pages",
+      "posts"
+    ]
+  )}`;
+}
+function describeDocumentTypes(documents) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const document of documents) {
+    counts.set(document.type, (counts.get(document.type) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([type, count]) => `${type}=${count}`).join(", ") || "none";
+}
+function safeUrl(value) {
+  try {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return "<invalid-url>";
+  }
+}
+function formatList(values) {
+  return values.length > 0 ? values.join(",") : "none";
+}
+function formatDuration(ms) {
+  return `${ms.toFixed(1)}ms`;
+}
+async function fetchCmsDocuments(config, dependencies) {
+  if (dependencies.fetchCmsDocuments) {
+    return dependencies.fetchCmsDocuments(config);
+  }
+  if (config.provider === "prismic") {
+    const loadDocuments = dependencies.fetchPrismicDocuments ?? ((cmsConfig) => {
+      if (cmsConfig.provider !== "prismic") {
+        throw new ConfigLoadError(
+          `fetchPrismicDocuments cannot load ${cmsConfig.provider}`
+        );
+      }
+      return defaultFetchPrismicDocuments(cmsConfig, {
+        fetch: dependencies.fetch
+      });
+    });
+    return loadDocuments(config);
+  }
+  if (config.provider === "strapi") {
+    return defaultFetchStrapiDocuments(config, { fetch: dependencies.fetch });
+  }
+  if (config.provider === "directus") {
+    return defaultFetchDirectusDocuments(config, { fetch: dependencies.fetch });
+  }
+  return defaultFetchWordPressDocuments(config, { fetch: dependencies.fetch });
+}
+function assertTypeFilterMatched(documents, types) {
+  if (types.length === 0) {
+    return;
+  }
+  if (documents.some((document) => types.includes(document.type))) {
+    return;
+  }
+  const availableTypes = [
+    ...new Set(documents.map((document) => document.type))
+  ].sort().join(", ");
+  throw new ConfigLoadError(
+    `No CMS documents matched --type ${types.join(", ")}. Available types: ${availableTypes || "none"}`
+  );
+}
+function parseCheckGroups(values) {
+  const allowed = /* @__PURE__ */ new Set(["routes", "seo", "a11y", "images", "fields"]);
+  const groups = splitList(values);
+  for (const group of groups) {
+    if (!allowed.has(group)) {
+      throw new ConfigLoadError(
+        `Unknown check group "${group}". Expected one of: ${[...allowed].join(", ")}`
+      );
+    }
+  }
+  return groups;
+}
+function parseTimeout(value) {
+  if (!value) {
+    return void 0;
+  }
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    throw new ConfigLoadError("--timeout must be a positive integer");
+  }
+  return timeout;
+}
+function parseConcurrency(value) {
+  if (!value) {
+    return void 0;
+  }
+  const concurrency = Number(value);
+  if (!Number.isInteger(concurrency) || concurrency <= 0) {
+    throw new ConfigLoadError("--concurrency must be a positive integer");
+  }
+  return concurrency;
+}
+function parseRetries(value) {
+  if (!value) {
+    return void 0;
+  }
+  const retries = Number(value);
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new ConfigLoadError("--retries must be a non-negative integer");
+  }
+  return retries;
+}
+function parseOptionalThreshold(value, flag) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const threshold = Number(value);
+  if (!Number.isInteger(threshold) || threshold < 0) {
+    throw new ConfigLoadError(`${flag} must be a non-negative integer`);
+  }
+  return threshold;
+}
+async function fetchSite(url, fetchImpl, timeoutMs, retries) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await (fetchImpl ?? fetch)(url, {
+        method: "GET",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        lastError = new Error(`Site ${url} returned HTTP ${response.status}`);
+        if (attempt >= retries) {
+          break;
+        }
+        continue;
+      }
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retries) {
+        break;
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  throw new SiteUnreachableError(messageFrom(lastError));
+}
+function parseFailOn(value) {
+  const level = value ?? "error";
+  if (level === "error" || level === "warning" || level === "never") {
+    return level;
+  }
+  throw new ConfigLoadError("--fail-on must be one of: error, warning, never");
+}
+function exitCodeForResult(result, options) {
+  const { failOn, maxWarnings, maxInfo } = options;
+  if (failOn === "never") {
+    return thresholdExceeded(result, maxWarnings, maxInfo) ? 1 : 0;
+  }
+  if (result.summary.errors > 0) {
+    return 1;
+  }
+  if (failOn === "warning" && result.summary.warnings > 0) {
+    return 1;
+  }
+  if (thresholdExceeded(result, maxWarnings, maxInfo)) {
+    return 1;
+  }
+  return 0;
+}
+function thresholdExceeded(result, maxWarnings, maxInfo) {
+  return maxWarnings !== void 0 && result.summary.warnings > maxWarnings || maxInfo !== void 0 && result.summary.info > maxInfo;
+}
+async function maybeWriteReport(report, result, cwd) {
+  if (!report) {
+    return;
+  }
+  const path = reportPathFromOption(report, cwd);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, renderHtmlReport(result), "utf8");
+}
+function reportPathFromOption(report, cwd) {
+  return resolve(
+    cwd,
+    typeof report === "string" ? report : ".cms-lab/report.html"
+  );
+}
+async function maybeWriteMarkdown(markdown, result, status, cwd) {
+  if (!markdown) {
+    return;
+  }
+  const path = markdownPathFromOption(markdown, cwd);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, renderMarkdownSummary(result, status), "utf8");
+}
+function markdownPathFromOption(markdown, cwd) {
+  return resolve(
+    cwd,
+    typeof markdown === "string" ? markdown : ".cms-lab/summary.md"
+  );
+}
+async function maybeWriteJUnit(junit, result, cwd) {
+  if (!junit) {
+    return;
+  }
+  const path = junitPathFromOption(junit, cwd);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, renderJUnitReport(result), "utf8");
+}
+function junitPathFromOption(junit, cwd) {
+  return resolve(cwd, typeof junit === "string" ? junit : ".cms-lab/junit.xml");
+}
+async function maybePostSlack(options) {
+  if (!options.webhookUrl) {
+    return false;
+  }
+  if (!shouldNotify(options.notifyOn, options.result, options.status)) {
+    return false;
+  }
+  await postSlackPayload({
+    webhookUrl: options.webhookUrl,
+    fetchImpl: options.fetchImpl,
+    payload: renderSlackPayload(options.result, options.status)
+  });
+  return true;
+}
+function shouldNotify(notifyOn, result, status) {
+  if (notifyOn === "always") {
+    return true;
+  }
+  if (notifyOn === "failure") {
+    return status === "failed";
+  }
+  return result.diagnostics.length > 0;
+}
+function parseNotifyOn(value) {
+  const notifyOn = value ?? "failure";
+  if (notifyOn === "always" || notifyOn === "failure" || notifyOn === "diagnostics") {
+    return notifyOn;
+  }
+  throw new ConfigLoadError(
+    "--notify-on must be one of: always, failure, diagnostics"
+  );
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function plural3(value, singular) {
+  return value === 1 ? singular : `${singular}s`;
+}
+function starterConfig(options) {
+  return `import { defineConfig } from "@cms-lab/core";
+
+export default defineConfig({
+  site: { url: ${JSON.stringify(options.url)} },
+  framework: { type: "next", router: "app" },
+  cms: {
+    provider: "prismic",
+    repositoryName: ${JSON.stringify(options.repository)},
+    accessToken: process.env.PRISMIC_ACCESS_TOKEN,
+  },
+  routes: [
+    { type: "page", pattern: "/:uid", getPath: (doc) => \`/\${doc.uid}\` },
+    {
+      type: "blog_post",
+      pattern: "/blog/:uid",
+      getPath: (doc) => \`/blog/\${doc.uid}\`,
+    },
+  ],
+});
+`;
+}
+
+export {
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { FetchLike, CmsProviderConfig, CMSDocument } from '@cms-lab/core';
+
+type CliDependencies = {
+    cwd?: string;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+    env?: Record<string, string | undefined>;
+    isStdoutTTY?: boolean;
+    fetch?: FetchLike;
+    fetchCmsDocuments?: (config: CmsProviderConfig) => Promise<CMSDocument[]>;
+    fetchPrismicDocuments?: (config: CmsProviderConfig) => Promise<CMSDocument[]>;
+};
+declare function runCli(argv: string[], dependencies?: CliDependencies): Promise<number>;
+
+export { type CliDependencies, runCli };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  runCli
+} from "./chunk-JHH7PD4C.js";
+export {
+  runCli
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@cms-lab/cli",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Catch CMS bugs before deploy.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/i-afaqrashid/cms-lab.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://cms-lab.dev",
+  "bugs": {
+    "url": "https://github.com/i-afaqrashid/cms-lab/issues"
+  },
+  "keywords": [
+    "cms",
+    "nextjs",
+    "prismic",
+    "strapi",
+    "directus",
+    "wordpress",
+    "cli",
+    "testing"
+  ],
+  "bin": {
+    "cms-lab": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "picocolors": "^1.1.1",
+    "@cms-lab/core": "1.0.1",
+    "@cms-lab/directus": "1.0.1",
+    "@cms-lab/next": "1.0.1",
+    "@cms-lab/reporter": "1.0.1",
+    "@cms-lab/strapi": "1.0.1",
+    "@cms-lab/wordpress": "1.0.1",
+    "@cms-lab/prismic": "1.0.1"
+  },
+  "author": "Afaq Rashid",
+  "scripts": {
+    "build": "tsup src/index.ts src/bin.ts --format esm --dts --clean --tsconfig ../../tsconfig.base.json"
+  }
+}