@chidchanun/bcp 0.1.21 → 0.1.23

package/packages/cli/src/developer-tools.ts

@@ -0,0 +1,1249 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createRequire,
+} from "node:module";
+
+import {
+  validateClientBoundaries,
+} from "../../bundler/src/client-boundary.js";
+import {
+  resolveBcpConfig,
+  type ResolvedBcpConfig,
+} from "../../config/src/index.js";
+import {
+  loadEnvironment,
+} from "../../env/src/index.js";
+import {
+  assertNoPageApiConflicts,
+  scanApiRoutes,
+  scanRoutes,
+} from "../../router/src/index.js";
+
+export type DoctorStatus =
+  | "pass"
+  | "warn"
+  | "fail";
+
+export interface DoctorCheck {
+  id: string;
+  status: DoctorStatus;
+  label: string;
+  message: string;
+}
+
+export interface DoctorReport {
+  frameworkVersion: string;
+  rootDirectory: string;
+  runtime: {
+    node: string;
+    platform: NodeJS.Platform;
+    arch: string;
+  };
+  checks: DoctorCheck[];
+  summary: {
+    passed: number;
+    warnings: number;
+    failed: number;
+  };
+}
+
+export interface InspectReport {
+  frameworkVersion: string;
+  rootDirectory: string;
+  runtime: {
+    node: string;
+    platform: NodeJS.Platform;
+    arch: string;
+  };
+  environment: {
+    mode: "development";
+    files: string[];
+    publicVariables: string[];
+  };
+  config: {
+    file: string | null;
+    resolved: ResolvedBcpConfig;
+  };
+  dependencies: {
+    bcp: string | null;
+    react: string | null;
+    reactDom: string | null;
+  };
+  routes: {
+    pages: Array<{
+      pathname: string;
+      file: string;
+    }>;
+    api: Array<{
+      pathname: string;
+      file: string;
+    }>;
+  };
+}
+
+interface DeveloperToolOptions {
+  rootDirectory: string;
+  frameworkVersion: string;
+  json?: boolean;
+}
+
+interface PackageManifestInfo {
+  version: string;
+  manifestPath: string;
+  packageRoot: string;
+}
+
+interface ProjectPackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+const MINIMUM_NODE_VERSION =
+  "24.11.0";
+
+const frameworkRequire =
+  createRequire(
+    import.meta.url
+  );
+
+export async function runDoctor(
+  options: DeveloperToolOptions
+): Promise<DoctorReport> {
+  const report =
+    await collectDoctorReport(
+      options
+    );
+
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        report,
+        null,
+        2
+      )
+    );
+  } else {
+    printDoctorReport(
+      report
+    );
+  }
+
+  if (
+    report.summary.failed > 0
+  ) {
+    process.exitCode = 1;
+  }
+
+  return report;
+}
+
+export async function runInspect(
+  options: DeveloperToolOptions
+): Promise<InspectReport> {
+  try {
+    const report =
+      await collectInspectReport(
+        options
+      );
+
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          report,
+          null,
+          2
+        )
+      );
+    } else {
+      printInspectReport(
+        report
+      );
+    }
+
+    return report;
+  } catch (error) {
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            frameworkVersion:
+              options.frameworkVersion,
+            rootDirectory:
+              options.rootDirectory,
+            error:
+              errorMessage(
+                error
+              ),
+          },
+          null,
+          2
+        )
+      );
+      process.exitCode = 1;
+      throw new DeveloperToolJsonError();
+    }
+
+    throw error;
+  }
+}
+
+export async function collectDoctorReport(
+  options: DeveloperToolOptions
+): Promise<DoctorReport> {
+  const rootDirectory =
+    path.resolve(
+      options.rootDirectory
+    );
+  const checks:
+    DoctorCheck[] = [];
+
+  addCheck(
+    checks,
+    "runtime.node",
+    compareVersions(
+      process.versions.node,
+      MINIMUM_NODE_VERSION
+    ) >= 0
+      ? "pass"
+      : "fail",
+    "Node.js runtime",
+    compareVersions(
+      process.versions.node,
+      MINIMUM_NODE_VERSION
+    ) >= 0
+      ? `Node.js ${process.versions.node} satisfies >=${MINIMUM_NODE_VERSION}.`
+      : `Node.js ${process.versions.node} is unsupported; BCP requires >=${MINIMUM_NODE_VERSION}.`
+  );
+
+  const packageFile =
+    path.join(
+      rootDirectory,
+      "package.json"
+    );
+
+  let projectPackage:
+    ProjectPackageJson | null = null;
+
+  if (
+    !fs.existsSync(
+      packageFile
+    )
+  ) {
+    addCheck(
+      checks,
+      "project.package",
+      "fail",
+      "Project package",
+      "package.json was not found in the project root."
+    );
+  } else {
+    try {
+      projectPackage =
+        readProjectPackage(
+          packageFile
+        );
+
+      addCheck(
+        checks,
+        "project.package",
+        "pass",
+        "Project package",
+        "package.json is readable."
+      );
+    } catch (error) {
+      addCheck(
+        checks,
+        "project.package",
+        "fail",
+        "Project package",
+        errorMessage(
+          error
+        )
+      );
+    }
+  }
+
+  const appDirectory =
+    path.join(
+      rootDirectory,
+      "app"
+    );
+  const hasAppDirectory =
+    isDirectory(
+      appDirectory
+    );
+
+  addCheck(
+    checks,
+    "project.app",
+    hasAppDirectory
+      ? "pass"
+      : "fail",
+    "App directory",
+    hasAppDirectory
+      ? "app/ is present."
+      : "app/ was not found. BCP page and API routes are discovered from this directory."
+  );
+
+  const publicDirectory =
+    path.join(
+      rootDirectory,
+      "public"
+    );
+
+  addCheck(
+    checks,
+    "project.public",
+    isDirectory(
+      publicDirectory
+    )
+      ? "pass"
+      : "warn",
+    "Public directory",
+    isDirectory(
+      publicDirectory
+    )
+      ? "public/ is present."
+      : "public/ is not present. This is valid when the application has no static assets."
+  );
+
+  if (projectPackage) {
+    const declared =
+      findDeclaredFrameworkDependency(
+        projectPackage
+      );
+
+    if (
+      declared?.name === "bcp"
+    ) {
+      addCheck(
+        checks,
+        "dependencies.bcp",
+        "pass",
+        "BCP dependency",
+        `bcp is declared as ${declared.range}.`
+      );
+    } else if (declared) {
+      addCheck(
+        checks,
+        "dependencies.bcp",
+        "warn",
+        "BCP dependency",
+        `${declared.name} is declared as ${declared.range}. The documented application import name is bcp.`
+      );
+    } else {
+      addCheck(
+        checks,
+        "dependencies.bcp",
+        "fail",
+        "BCP dependency",
+        "Neither bcp nor @chidchanun/bcp is declared in dependencies/devDependencies."
+      );
+    }
+  }
+
+  const appReact =
+    resolveInstalledPackage(
+      packageFile,
+      "react"
+    );
+  const appReactDom =
+    resolveInstalledPackage(
+      packageFile,
+      "react-dom"
+    );
+  const appBcp =
+    resolveInstalledPackage(
+      packageFile,
+      "bcp"
+    ) ??
+    resolveInstalledPackage(
+      packageFile,
+      "@chidchanun/bcp"
+    );
+
+  addInstalledPackageCheck(
+    checks,
+    "dependencies.installed-bcp",
+    "Installed BCP package",
+    appBcp
+  );
+  addInstalledPackageCheck(
+    checks,
+    "dependencies.react",
+    "React package",
+    appReact
+  );
+  addInstalledPackageCheck(
+    checks,
+    "dependencies.react-dom",
+    "React DOM package",
+    appReactDom
+  );
+
+  if (
+    appReact &&
+    appReactDom
+  ) {
+    addCheck(
+      checks,
+      "dependencies.react-version-parity",
+      appReact.version ===
+        appReactDom.version
+        ? "pass"
+        : "fail",
+      "React renderer version parity",
+      appReact.version ===
+        appReactDom.version
+        ? `react and react-dom both resolve to ${appReact.version}.`
+        : `react resolves to ${appReact.version} while react-dom resolves to ${appReactDom.version}. Install matching versions.`
+    );
+  }
+
+  const frameworkReact =
+    resolveFrameworkPackage(
+      "react"
+    );
+  const frameworkReactDom =
+    resolveFrameworkPackage(
+      "react-dom"
+    );
+
+  if (
+    appReact &&
+    frameworkReact
+  ) {
+    const sameReact =
+      samePackageRoot(
+        appReact,
+        frameworkReact
+      );
+
+    addCheck(
+      checks,
+      "dependencies.single-react",
+      sameReact
+        ? "pass"
+        : "fail",
+      "Single React instance",
+      sameReact
+        ? `BCP and the application resolve the same React package (${appReact.version}).`
+        : `BCP resolves React from ${frameworkReact.packageRoot}, but the application resolves React from ${appReact.packageRoot}. This can cause Invalid hook call errors.`
+    );
+  }
+
+  if (
+    appReactDom &&
+    frameworkReactDom
+  ) {
+    const sameRenderer =
+      samePackageRoot(
+        appReactDom,
+        frameworkReactDom
+      );
+
+    addCheck(
+      checks,
+      "dependencies.single-react-dom",
+      sameRenderer
+        ? "pass"
+        : "fail",
+      "Single React DOM renderer",
+      sameRenderer
+        ? `BCP and the application resolve the same React DOM package (${appReactDom.version}).`
+        : `BCP resolves react-dom from ${frameworkReactDom.packageRoot}, but the application resolves react-dom from ${appReactDom.packageRoot}. Avoid linked framework directories; test packed .tgz artifacts instead.`
+    );
+  }
+
+  try {
+    const environment =
+      loadEnvironment(
+        rootDirectory,
+        "development"
+      );
+
+    addCheck(
+      checks,
+      "environment.development",
+      "pass",
+      "Development environment",
+      environment.files.length > 0
+        ? `Loaded ${environment.files.join(", ")}. Public variables: ${Object.keys(environment.publicValues).length}.`
+        : "No development .env files were found; process environment and defaults remain available."
+    );
+  } catch (error) {
+    addCheck(
+      checks,
+      "environment.development",
+      "fail",
+      "Development environment",
+      errorMessage(
+        error
+      )
+    );
+  }
+
+  try {
+    const resolved =
+      await resolveBcpConfig(
+        rootDirectory
+      );
+
+    addCheck(
+      checks,
+      "config.resolved",
+      "pass",
+      "Framework config",
+      resolved.file
+        ? `${path.basename(resolved.file)} is valid; server resolves to ${resolved.config.server.hostname}:${resolved.config.server.port}.`
+        : `No bcp.config file found; defaults/environment resolve server to ${resolved.config.server.hostname}:${resolved.config.server.port}.`
+    );
+  } catch (error) {
+    addCheck(
+      checks,
+      "config.resolved",
+      "fail",
+      "Framework config",
+      errorMessage(
+        error
+      )
+    );
+  }
+
+  if (hasAppDirectory) {
+    try {
+      const pageRoutes =
+        scanRoutes(
+          appDirectory
+        );
+      const apiRoutes =
+        scanApiRoutes(
+          appDirectory
+        );
+
+      assertNoPageApiConflicts(
+        pageRoutes,
+        apiRoutes
+      );
+
+      addCheck(
+        checks,
+        "routes.discovery",
+        pageRoutes.length > 0 ||
+          apiRoutes.length > 0
+          ? "pass"
+          : "warn",
+        "Route discovery",
+        `Discovered ${pageRoutes.length} page route(s) and ${apiRoutes.length} API route(s).`
+      );
+
+      try {
+        validateClientBoundaries(
+          pageRoutes,
+          rootDirectory
+        );
+
+        addCheck(
+          checks,
+          "routes.client-boundaries",
+          "pass",
+          "Client boundaries",
+          "Hydrated routes do not expose detected server-only modules and client-hook directives are valid."
+        );
+      } catch (error) {
+        addCheck(
+          checks,
+          "routes.client-boundaries",
+          "fail",
+          "Client boundaries",
+          errorMessage(
+            error
+          )
+        );
+      }
+    } catch (error) {
+      addCheck(
+        checks,
+        "routes.discovery",
+        "fail",
+        "Route discovery",
+        errorMessage(
+          error
+        )
+      );
+    }
+  }
+
+  const summary = {
+    passed:
+      checks.filter(
+        (check) =>
+          check.status === "pass"
+      ).length,
+    warnings:
+      checks.filter(
+        (check) =>
+          check.status === "warn"
+      ).length,
+    failed:
+      checks.filter(
+        (check) =>
+          check.status === "fail"
+      ).length,
+  };
+
+  return {
+    frameworkVersion:
+      options.frameworkVersion,
+    rootDirectory,
+    runtime: {
+      node:
+        process.versions.node,
+      platform:
+        process.platform,
+      arch:
+        process.arch,
+    },
+    checks,
+    summary,
+  };
+}
+
+export async function collectInspectReport(
+  options: DeveloperToolOptions
+): Promise<InspectReport> {
+  const rootDirectory =
+    path.resolve(
+      options.rootDirectory
+    );
+  const packageFile =
+    path.join(
+      rootDirectory,
+      "package.json"
+    );
+  const appDirectory =
+    path.join(
+      rootDirectory,
+      "app"
+    );
+
+  const environment =
+    loadEnvironment(
+      rootDirectory,
+      "development"
+    );
+  const resolved =
+    await resolveBcpConfig(
+      rootDirectory
+    );
+  const pageRoutes =
+    scanRoutes(
+      appDirectory
+    );
+  const apiRoutes =
+    scanApiRoutes(
+      appDirectory
+    );
+
+  assertNoPageApiConflicts(
+    pageRoutes,
+    apiRoutes
+  );
+  validateClientBoundaries(
+    pageRoutes,
+    rootDirectory
+  );
+
+  const bcp =
+    resolveInstalledPackage(
+      packageFile,
+      "bcp"
+    ) ??
+    resolveInstalledPackage(
+      packageFile,
+      "@chidchanun/bcp"
+    );
+  const react =
+    resolveInstalledPackage(
+      packageFile,
+      "react"
+    );
+  const reactDom =
+    resolveInstalledPackage(
+      packageFile,
+      "react-dom"
+    );
+
+  return {
+    frameworkVersion:
+      options.frameworkVersion,
+    rootDirectory,
+    runtime: {
+      node:
+        process.versions.node,
+      platform:
+        process.platform,
+      arch:
+        process.arch,
+    },
+    environment: {
+      mode:
+        "development",
+      files:
+        environment.files,
+      publicVariables:
+        Object.keys(
+          environment.publicValues
+        ).sort(),
+    },
+    config: {
+      file:
+        resolved.file
+          ? path.basename(
+              resolved.file
+            )
+          : null,
+      resolved:
+        resolved.config,
+    },
+    dependencies: {
+      bcp:
+        bcp?.version ??
+        null,
+      react:
+        react?.version ??
+        null,
+      reactDom:
+        reactDom?.version ??
+        null,
+    },
+    routes: {
+      pages:
+        pageRoutes.map(
+          (route) => ({
+            pathname:
+              route.pathname,
+            file:
+              relativeProjectPath(
+                rootDirectory,
+                route.filePath
+              ),
+          })
+        ),
+      api:
+        apiRoutes.map(
+          (route) => ({
+            pathname:
+              route.pathname,
+            file:
+              relativeProjectPath(
+                rootDirectory,
+                route.filePath
+              ),
+          })
+        ),
+    },
+  };
+}
+
+export function compareVersions(
+  left: string,
+  right: string
+): number {
+  const leftParts =
+    parseVersionParts(
+      left
+    );
+  const rightParts =
+    parseVersionParts(
+      right
+    );
+
+  for (
+    let index = 0;
+    index < 3;
+    index++
+  ) {
+    if (
+      leftParts[index] >
+      rightParts[index]
+    ) {
+      return 1;
+    }
+
+    if (
+      leftParts[index] <
+      rightParts[index]
+    ) {
+      return -1;
+    }
+  }
+
+  return 0;
+}
+
+function printDoctorReport(
+  report: DoctorReport
+): void {
+  console.log("");
+  console.log(
+    `BCP Doctor v${report.frameworkVersion}`
+  );
+  console.log(
+    `Project: ${report.rootDirectory}`
+  );
+  console.log(
+    `Runtime: Node.js ${report.runtime.node} | ${report.runtime.platform} ${report.runtime.arch}`
+  );
+  console.log("");
+
+  for (const check of report.checks) {
+    const marker =
+      check.status === "pass"
+        ? "PASS"
+        : check.status === "warn"
+          ? "WARN"
+          : "FAIL";
+
+    console.log(
+      `[${marker}] ${check.label}: ${check.message}`
+    );
+  }
+
+  console.log("");
+  console.log(
+    `Summary: ${report.summary.passed} passed, ${report.summary.warnings} warning(s), ${report.summary.failed} failed.`
+  );
+  console.log("");
+}
+
+function printInspectReport(
+  report: InspectReport
+): void {
+  console.log("");
+  console.log(
+    `BCP Inspect v${report.frameworkVersion}`
+  );
+  console.log(
+    `Project: ${report.rootDirectory}`
+  );
+  console.log(
+    `Runtime: Node.js ${report.runtime.node} | ${report.runtime.platform} ${report.runtime.arch}`
+  );
+  console.log("");
+  console.log(
+    "Environment:"
+  );
+  console.log(
+    `  mode: ${report.environment.mode}`
+  );
+  console.log(
+    `  files: ${report.environment.files.length > 0 ? report.environment.files.join(", ") : "(none)"}`
+  );
+  console.log(
+    `  public variables: ${report.environment.publicVariables.length > 0 ? report.environment.publicVariables.join(", ") : "(none)"}`
+  );
+  console.log("");
+  console.log(
+    "Dependencies:"
+  );
+  console.log(
+    `  bcp: ${report.dependencies.bcp ?? "not resolved"}`
+  );
+  console.log(
+    `  react: ${report.dependencies.react ?? "not resolved"}`
+  );
+  console.log(
+    `  react-dom: ${report.dependencies.reactDom ?? "not resolved"}`
+  );
+  console.log("");
+  console.log(
+    `Config: ${report.config.file ?? "defaults/environment"}`
+  );
+  console.log(
+    JSON.stringify(
+      report.config.resolved,
+      null,
+      2
+    )
+  );
+  console.log("");
+  console.log(
+    `Routes: ${report.routes.pages.length} page(s), ${report.routes.api.length} API route(s)`
+  );
+
+  for (const route of report.routes.pages) {
+    console.log(
+      `  PAGE ${route.pathname} -> ${route.file}`
+    );
+  }
+
+  for (const route of report.routes.api) {
+    console.log(
+      `  API  ${route.pathname} -> ${route.file}`
+    );
+  }
+
+  console.log("");
+}
+
+function addInstalledPackageCheck(
+  checks: DoctorCheck[],
+  id: string,
+  label: string,
+  info: PackageManifestInfo | null
+): void {
+  addCheck(
+    checks,
+    id,
+    info
+      ? "pass"
+      : "fail",
+    label,
+    info
+      ? `${info.version} at ${info.packageRoot}`
+      : "Package could not be resolved from the project."
+  );
+}
+
+function addCheck(
+  checks: DoctorCheck[],
+  id: string,
+  status: DoctorStatus,
+  label: string,
+  message: string
+): void {
+  checks.push({
+    id,
+    status,
+    label,
+    message,
+  });
+}
+
+function readProjectPackage(
+  packageFile: string
+): ProjectPackageJson {
+  const value =
+    JSON.parse(
+      fs.readFileSync(
+        packageFile,
+        "utf8"
+      )
+    );
+
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(
+      value
+    )
+  ) {
+    throw new Error(
+      "package.json must contain a JSON object."
+    );
+  }
+
+  return value as ProjectPackageJson;
+}
+
+function findDeclaredFrameworkDependency(
+  projectPackage: ProjectPackageJson
+): {
+  name: string;
+  range: string;
+} | null {
+  for (
+    const dependencies
+    of [
+      projectPackage.dependencies,
+      projectPackage.devDependencies,
+    ]
+  ) {
+    if (!dependencies) {
+      continue;
+    }
+
+    if (
+      dependencies.bcp
+    ) {
+      return {
+        name:
+          "bcp",
+        range:
+          dependencies.bcp,
+      };
+    }
+
+    if (
+      dependencies[
+        "@chidchanun/bcp"
+      ]
+    ) {
+      return {
+        name:
+          "@chidchanun/bcp",
+        range:
+          dependencies[
+            "@chidchanun/bcp"
+          ],
+      };
+    }
+  }
+
+  return null;
+}
+
+function resolveInstalledPackage(
+  projectPackageFile: string,
+  packageName: string
+): PackageManifestInfo | null {
+  if (
+    !fs.existsSync(
+      projectPackageFile
+    )
+  ) {
+    return null;
+  }
+
+  try {
+    const projectRequire =
+      createRequire(
+        projectPackageFile
+      );
+
+    return resolvePackageWithRequire(
+      projectRequire,
+      packageName
+    );
+  } catch {
+    return null;
+  }
+}
+
+function resolveFrameworkPackage(
+  packageName: string
+): PackageManifestInfo | null {
+  try {
+    return resolvePackageWithRequire(
+      frameworkRequire,
+      packageName
+    );
+  } catch {
+    return null;
+  }
+}
+
+function resolvePackageWithRequire(
+  resolver: NodeJS.Require,
+  packageName: string
+): PackageManifestInfo {
+  let manifestPath:
+    string;
+
+  try {
+    manifestPath =
+      resolver.resolve(
+        `${packageName}/package.json`
+      );
+  } catch {
+    const entry =
+      resolver.resolve(
+        packageName
+      );
+    const discovered =
+      findNearestPackageManifest(
+        path.dirname(
+          entry
+        )
+      );
+
+    if (!discovered) {
+      throw new Error(
+        `Could not locate package.json for ${packageName}.`
+      );
+    }
+
+    manifestPath =
+      discovered;
+  }
+
+  const manifest =
+    JSON.parse(
+      fs.readFileSync(
+        manifestPath,
+        "utf8"
+      )
+    ) as {
+      version?: unknown;
+    };
+
+  if (
+    typeof manifest.version !==
+      "string"
+  ) {
+    throw new Error(
+      `${packageName} package.json does not contain a version.`
+    );
+  }
+
+  const packageRoot =
+    realPath(
+      path.dirname(
+        manifestPath
+      )
+    );
+
+  return {
+    version:
+      manifest.version,
+    manifestPath:
+      realPath(
+        manifestPath
+      ),
+    packageRoot,
+  };
+}
+
+function findNearestPackageManifest(
+  startDirectory: string
+): string | null {
+  let current =
+    path.resolve(
+      startDirectory
+    );
+
+  while (true) {
+    const candidate =
+      path.join(
+        current,
+        "package.json"
+      );
+
+    if (
+      fs.existsSync(
+        candidate
+      )
+    ) {
+      return candidate;
+    }
+
+    const parent =
+      path.dirname(
+        current
+      );
+
+    if (parent === current) {
+      return null;
+    }
+
+    current =
+      parent;
+  }
+}
+
+function samePackageRoot(
+  left: PackageManifestInfo,
+  right: PackageManifestInfo
+): boolean {
+  const normalize =
+    (value: string) =>
+      process.platform === "win32"
+        ? value.toLowerCase()
+        : value;
+
+  return normalize(
+    left.packageRoot
+  ) === normalize(
+    right.packageRoot
+  );
+}
+
+function realPath(
+  value: string
+): string {
+  try {
+    return fs.realpathSync(
+      value
+    );
+  } catch {
+    return path.resolve(
+      value
+    );
+  }
+}
+
+function isDirectory(
+  directory: string
+): boolean {
+  try {
+    return fs.statSync(
+      directory
+    ).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function relativeProjectPath(
+  rootDirectory: string,
+  filePath: string
+): string {
+  return path.relative(
+    rootDirectory,
+    filePath
+  ).replace(
+    /\\/g,
+    "/"
+  );
+}
+
+function parseVersionParts(
+  version: string
+): [number, number, number] {
+  const match =
+    /^(\d+)\.(\d+)\.(\d+)/.exec(
+      version
+    );
+
+  if (!match) {
+    return [
+      0,
+      0,
+      0,
+    ];
+  }
+
+  return [
+    Number(
+      match[1]
+    ),
+    Number(
+      match[2]
+    ),
+    Number(
+      match[3]
+    ),
+  ];
+}
+
+function errorMessage(
+  error: unknown
+): string {
+  return error instanceof Error
+    ? error.message
+    : String(
+        error
+      );
+}
+
+class DeveloperToolJsonError extends Error {
+  constructor() {
+    super(
+      "BCP inspect failed."
+    );
+    this.name =
+      "DeveloperToolJsonError";
+  }
+}