@poetora/cli 0.0.1

package/bin/start.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/start.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { cli } from './cli.js';
+const packageName = process.env.POETORA_PACKAGE_NAME ?? 'poet';
+cli({ packageName });

package/bin/update.d.ts

@@ -0,0 +1,3 @@
+export declare const update: ({ packageName }: {
+    packageName: string;
+}) => Promise<void>;

package/bin/update.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SpinnerLog, SuccessLog, ErrorLog, addLog, clearLogs } from '@poetora/previewing';
+import { execAsync, getLatestCliVersion, getVersions, detectPackageManager } from './helpers.js';
+export const update = async ({ packageName }) => {
+    addLog(_jsx(SpinnerLog, { message: "updating..." }));
+    const { cli: existingCliVersion } = getVersions();
+    const latestCliVersion = getLatestCliVersion(packageName);
+    const isUpToDate = existingCliVersion && latestCliVersion && latestCliVersion.trim() === existingCliVersion.trim();
+    if (isUpToDate) {
+        addLog(_jsx(SuccessLog, { message: "already up to date" }));
+        return;
+    }
+    if (existingCliVersion && latestCliVersion.trim() !== existingCliVersion.trim()) {
+        try {
+            clearLogs();
+            addLog(_jsx(SpinnerLog, { message: `updating ${packageName} package...` }));
+            const packageManager = await detectPackageManager({ packageName });
+            if (packageManager === 'pnpm') {
+                await execAsync(`pnpm install -g ${packageName}@latest --silent`);
+            }
+            else {
+                await execAsync(`npm install -g ${packageName}@latest --silent`);
+            }
+        }
+        catch (err) {
+            addLog(_jsx(ErrorLog, { message: `failed to update ${packageName}@latest` }));
+            return;
+        }
+    }
+    clearLogs();
+    addLog(_jsx(SuccessLog, { message: `updated ${packageName} to the latest version: ${latestCliVersion}` }));
+};

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@poetora/cli",
+  "version": "0.0.1",
+  "description": "The CLI for Poetora documentation Engine",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Poetora",
+  "bugs": {
+    "url": "https://github.com/poetora/docs/issues"
+  },
+  "license": "Elastic-2.0",
+  "keywords": [
+    "poetora",
+    "poet",
+    "cli"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": "./bin/index.js",
+  "bin": {
+    "poet": "bin/index.js",
+    "poetora": "bin/index.js"
+  },
+  "scripts": {
+    "dev": "pnpm build && NODE_NO_WARNINGS=1 node bin/index.js",
+    "build": "tsc --project tsconfig.build.json",
+    "clean:build": "rimraf bin",
+    "clean:all": "rimraf node_modules .eslintcache && pnpm clean:build",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "type": "tsc --noEmit",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "7.9.0",
+    "@poetora/link-rot": "workspace:*",
+    "@poetora/prebuild": "workspace:*",
+    "@poetora/previewing": "workspace:*",
+    "@poetora/shared": "workspace:*",
+    "@poetora/validation": "workspace:*",
+    "adm-zip": "0.5.16",
+    "chalk": "5.2.0",
+    "color": "4.2.3",
+    "detect-port": "1.5.1",
+    "front-matter": "4.0.2",
+    "fs-extra": "11.2.0",
+    "ink": "6.3.0",
+    "inquirer": "12.3.0",
+    "js-yaml": "4.1.0",
+    "mdast-util-mdx-jsx": "3.2.0",
+    "react": "19.2.1",
+    "semver": "7.7.2",
+    "unist-util-visit": "5.0.0",
+    "yargs": "17.7.1"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "4.3.0",
+    "@tsconfig/recommended": "1.0.2",
+    "@types/adm-zip": "0.5.7",
+    "@types/color": "^3.0.3",
+    "@types/detect-port": "1.3.2",
+    "@types/fs-extra": "^9.0.13",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mdast": "4.0.4",
+    "@types/node": "catalog:",
+    "@types/yargs": "17.0.22",
+    "@typescript-eslint/eslint-plugin": "catalog:",
+    "@typescript-eslint/parser": "catalog:",
+    "eslint": "catalog:",
+    "eslint-config-prettier": "catalog:",
+    "openapi-types": "12.1.3",
+    "prettier": "3.1.1",
+    "rimraf": "5.0.1",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "vitest-mock-process": "1.0.4"
+  }
+}

package/src/accessibility.ts

@@ -0,0 +1,180 @@
+import Color from 'color';
+
+export const WCAG_STANDARDS = {
+  AA_NORMAL: 4.5,
+  AA_LARGE: 3,
+  AAA_NORMAL: 7,
+  AAA_LARGE: 4.5,
+} as const;
+
+export type ContrastResult = {
+  ratio: number;
+  meetsAA: boolean;
+  meetsAAA: boolean;
+  recommendation: 'pass' | 'warning' | 'fail';
+  message: string;
+};
+
+export function checkColorContrast(
+  foreground: string,
+  background: string,
+  minThreshold: number = WCAG_STANDARDS.AA_NORMAL
+): ContrastResult | null {
+  try {
+    const fg = Color(foreground);
+    const bg = Color(background);
+
+    const ratio = fg.contrast(bg);
+    const level = fg.level(bg);
+
+    const meetsAA = level === 'AA' || level === 'AAA';
+    const meetsAAA = level === 'AAA';
+
+    let recommendation: 'pass' | 'warning' | 'fail';
+    let message: string;
+
+    if (minThreshold !== WCAG_STANDARDS.AA_NORMAL) {
+      if (ratio >= minThreshold) {
+        recommendation = 'pass';
+        message = `Contrast ratio: ${ratio.toFixed(
+          2
+        )}:1 (meets minimum threshold of ${minThreshold}:1)`;
+      } else {
+        recommendation = 'fail';
+        message = `Poor contrast ratio: ${ratio.toFixed(
+          2
+        )}:1 (fails minimum threshold, required: ${minThreshold}:1)`;
+      }
+    } else {
+      if (meetsAAA) {
+        recommendation = 'pass';
+        message = `Excellent contrast ratio: ${ratio.toFixed(2)}:1 (meets WCAG AAA)`;
+      } else if (meetsAA) {
+        recommendation = 'warning';
+        message = `Good contrast ratio: ${ratio.toFixed(
+          2
+        )}:1 (meets WCAG AA, consider AAA for better accessibility)`;
+      } else {
+        recommendation = 'fail';
+        message = `Poor contrast ratio: ${ratio.toFixed(2)}:1 (fails WCAG AA, minimum required: ${
+          WCAG_STANDARDS.AA_NORMAL
+        }:1)`;
+      }
+    }
+
+    return {
+      ratio,
+      meetsAA,
+      meetsAAA,
+      recommendation,
+      message,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface AccessibilityCheckResult {
+  primaryContrast: ContrastResult | null;
+  lightContrast: ContrastResult | null;
+  darkContrast: ContrastResult | null;
+  darkOnLightContrast: ContrastResult | null;
+  anchorResults: Array<{
+    name: string;
+    lightContrast: ContrastResult | null;
+    darkContrast: ContrastResult | null;
+  }>;
+  overallScore: 'pass' | 'warning' | 'fail';
+}
+
+export function checkDocsColors(
+  colors: {
+    primary?: string;
+    light?: string;
+    dark?: string;
+  },
+  background: {
+    lightHex: string;
+    darkHex: string;
+  },
+  navigation?: {
+    global?: {
+      anchors?: Array<{
+        anchor: string;
+        color?: {
+          light?: string;
+          dark?: string;
+        };
+      }>;
+    };
+  }
+): AccessibilityCheckResult {
+  const lightBackground = background.lightHex;
+  const darkBackground = background.darkHex;
+
+  const primaryContrast = colors.primary
+    ? checkColorContrast(colors.primary, lightBackground)
+    : null;
+
+  const lightContrast = colors.light ? checkColorContrast(colors.light, darkBackground) : null;
+
+  const darkContrast = colors.dark ? checkColorContrast(colors.dark, darkBackground, 3) : null;
+
+  const darkOnLightContrast = colors.dark
+    ? checkColorContrast(colors.dark, lightBackground, 3)
+    : null;
+
+  const anchorResults: Array<{
+    name: string;
+    lightContrast: ContrastResult | null;
+    darkContrast: ContrastResult | null;
+  }> = [];
+
+  if (navigation?.global?.anchors) {
+    for (const anchor of navigation.global.anchors) {
+      if (anchor.color) {
+        const lightContrast = anchor.color.light
+          ? checkColorContrast(anchor.color.light, lightBackground)
+          : null;
+        const darkContrast = anchor.color.dark
+          ? checkColorContrast(anchor.color.dark, darkBackground)
+          : null;
+
+        anchorResults.push({
+          name: anchor.anchor,
+          lightContrast,
+          darkContrast,
+        });
+      }
+    }
+  }
+
+  const results = [
+    primaryContrast,
+    lightContrast,
+    darkContrast,
+    darkOnLightContrast,
+    ...anchorResults.flatMap((anchor) => [anchor.lightContrast, anchor.darkContrast]),
+  ].filter(Boolean);
+
+  const hasFailure = results.some((result) => result!.recommendation === 'fail');
+  const hasWarning = results.some((result) => result!.recommendation === 'warning');
+
+  let overallScore: 'pass' | 'warning' | 'fail';
+  if (hasFailure) {
+    overallScore = 'fail';
+  } else if (hasWarning) {
+    overallScore = 'warning';
+  } else {
+    overallScore = 'pass';
+  }
+
+  return {
+    primaryContrast,
+    lightContrast,
+    darkContrast,
+    darkOnLightContrast,
+    anchorResults,
+    overallScore,
+  };
+}

package/src/accessibilityCheck.tsx

@@ -0,0 +1,145 @@
+import { getConfigObj, getConfigPath } from '@poetora/prebuild';
+import { addLog, ErrorLog, WarningLog } from '@poetora/previewing';
+import { getBackgroundColors } from '@poetora/shared';
+import { Text } from 'ink';
+
+import { checkDocsColors, type AccessibilityCheckResult } from './accessibility.js';
+import { ContrastResult } from './accessibility.js';
+import { CMD_EXEC_PATH } from './constants.js';
+
+export type TerminateCode = 0 | 1;
+
+export const accessibilityCheck = async (): Promise<TerminateCode> => {
+  try {
+    const docsConfigPath = await getConfigPath(CMD_EXEC_PATH);
+
+    if (!docsConfigPath) {
+      addLog(
+        <ErrorLog message="No configuration file found. Please run this command from a directory with a docs.json file." />
+      );
+      return 1;
+    }
+
+    const config = await getConfigObj(CMD_EXEC_PATH);
+
+    if (!config.colors) {
+      addLog(<WarningLog message="No colors section found in configuration file" />);
+      return 0;
+    }
+
+    const { colors, navigation } = config;
+
+    const { lightHex, darkHex } = getBackgroundColors(config);
+
+    const results: AccessibilityCheckResult = checkDocsColors(
+      colors,
+      { lightHex, darkHex },
+      navigation
+    );
+
+    const displayContrastResult = (
+      result: ContrastResult | null,
+      label: string,
+      prefix: string = ''
+    ) => {
+      if (!result) return;
+
+      const { recommendation, message } = result;
+      const icon =
+        recommendation === 'pass' ? 'PASS' : recommendation === 'warning' ? 'WARN' : 'FAIL';
+      const color =
+        recommendation === 'pass' ? 'green' : recommendation === 'warning' ? 'yellow' : 'red';
+
+      addLog(
+        <Text>
+          <Text bold={prefix === ''}>
+            {prefix}
+            {label}:{' '}
+          </Text>
+          <Text color={color}>
+            {icon} {message}
+          </Text>
+        </Text>
+      );
+    };
+
+    addLog(
+      <Text bold color="cyan">
+        Checking color accessibility...
+      </Text>
+    );
+    addLog(<Text></Text>);
+
+    displayContrastResult(
+      results.primaryContrast,
+      `Primary Color (${colors.primary}) vs Light Background`
+    );
+    displayContrastResult(
+      results.lightContrast,
+      `Light Color (${colors.light}) vs Dark Background`
+    );
+    displayContrastResult(results.darkContrast, `Dark Color (${colors.dark}) vs Dark Background`);
+    displayContrastResult(
+      results.darkOnLightContrast,
+      `Dark Color (${colors.dark}) vs Light Background`
+    );
+
+    const anchorsWithResults = results.anchorResults.filter(
+      (anchor) => anchor.lightContrast || anchor.darkContrast
+    );
+
+    if (anchorsWithResults.length > 0) {
+      addLog(<Text></Text>);
+      addLog(
+        <Text bold color="cyan">
+          Navigation Anchors:
+        </Text>
+      );
+
+      for (const anchor of anchorsWithResults) {
+        addLog(<Text bold> {anchor.name}:</Text>);
+        displayContrastResult(anchor.lightContrast, 'Light variant vs Light Background', '    ');
+        displayContrastResult(anchor.darkContrast, 'Dark variant vs Dark Background', '    ');
+      }
+    }
+
+    addLog(<Text></Text>);
+    const overallIcon =
+      results.overallScore === 'pass'
+        ? 'PASS'
+        : results.overallScore === 'warning'
+          ? 'WARN'
+          : 'FAIL';
+    const overallColor =
+      results.overallScore === 'pass'
+        ? 'green'
+        : results.overallScore === 'warning'
+          ? 'yellow'
+          : 'red';
+    const overallMessage =
+      results.overallScore === 'pass'
+        ? 'All colors meet accessibility standards!'
+        : results.overallScore === 'warning'
+          ? 'Some colors could be improved for better accessibility'
+          : 'Some colors fail accessibility standards and should be updated';
+
+    addLog(
+      <Text>
+        <Text bold color={overallColor}>
+          Overall Assessment: {overallIcon} {overallMessage}
+        </Text>
+      </Text>
+    );
+
+    return results.overallScore === 'fail' ? 1 : 0;
+  } catch (error) {
+    addLog(
+      <ErrorLog
+        message={`Accessibility check failed: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`}
+      />
+    );
+    return 1;
+  }
+};