@next-vibe/checker 1.0.11 → 1.0.13

package/src/app/api/[locale]/system/help/interactive/route.ts

@@ -0,0 +1,53 @@
+/**
+ * Interactive Mode Route Handler
+ * Handles POST requests for starting interactive CLI mode
+ */
+
+import "server-only";
+
+import {
+  ErrorResponseTypes,
+  fail,
+} from "next-vibe/shared/types/response.schema";
+
+import type { CliCompatiblePlatform } from "@/app/api/[locale]/system/unified-interface/cli/runtime/route-executor";
+import { endpointsHandler } from "@/app/api/[locale]/system/unified-interface/shared/endpoints/route/multi";
+import { Methods } from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+import { Platform } from "@/app/api/[locale]/system/unified-interface/shared/types/platform";
+
+import interactiveEndpoints from "./definition";
+import { interactiveRepository } from "./repository";
+
+const CLI_PLATFORMS: readonly Platform[] = [
+  Platform.CLI,
+  Platform.CLI_PACKAGE,
+  Platform.AI,
+  Platform.MCP,
+];
+
+function isCliCompatiblePlatform(
+  platform: Platform,
+): platform is CliCompatiblePlatform {
+  return CLI_PLATFORMS.includes(platform);
+}
+
+export const { POST, tools } = endpointsHandler({
+  endpoint: interactiveEndpoints,
+  [Methods.POST]: {
+    handler: ({ user, locale, logger, platform }) => {
+      if (!isCliCompatiblePlatform(platform)) {
+        return fail({
+          message: "app.api.system.help.interactive.errors.cliOnly.title",
+          errorType: ErrorResponseTypes.BAD_REQUEST,
+        });
+      }
+
+      return interactiveRepository.startInteractiveMode(
+        user,
+        locale,
+        logger,
+        platform,
+      );
+    },
+  },
+});

package/src/app/api/[locale]/system/help/list/definition.ts

@@ -0,0 +1,372 @@
+/**
+ * Help List Command Endpoint Definition
+ * Production-ready endpoint for listing all available CLI commands
+ */
+
+import { z } from "zod";
+
+import { createEndpoint } from "@/app/api/[locale]/system/unified-interface/shared/endpoints/definition/create";
+import {
+  objectField,
+  requestDataField,
+  responseArrayField,
+  responseField,
+} from "@/app/api/[locale]/system/unified-interface/shared/field/utils";
+import {
+  EndpointErrorTypes,
+  FieldDataType,
+  LayoutType,
+  Methods,
+  WidgetType,
+} from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+
+import { UserRole } from "../../../user/user-roles/enum";
+
+const { POST } = createEndpoint({
+  method: Methods.POST,
+  path: ["system", "help", "list"],
+  title: "app.api.system.help.list.post.title",
+  description: "app.api.system.help.list.post.description",
+  category: "app.api.system.help.category",
+  tags: ["app.api.system.help.list.tag"],
+  icon: "info",
+  allowedRoles: [
+    UserRole.ADMIN,
+    UserRole.AI_TOOL_OFF,
+    UserRole.MCP_OFF,
+    UserRole.PRODUCTION_OFF,
+    UserRole.CLI_AUTH_BYPASS,
+  ],
+  aliases: ["list", "ls", "commands"],
+
+  fields: objectField(
+    {
+      type: WidgetType.CONTAINER,
+      layoutType: LayoutType.GRID,
+      columns: 12,
+    },
+    { request: "data", response: true },
+    {
+      // === REQUEST FIELDS ===
+      category: requestDataField(
+        {
+          type: WidgetType.FORM_FIELD,
+          fieldType: FieldDataType.TEXT,
+          label: "app.api.system.help.list.fields.category.label",
+          description: "app.api.system.help.list.fields.category.description",
+          placeholder: "app.api.system.help.list.fields.category.placeholder",
+          columns: 6,
+        },
+        z.string().optional(),
+      ),
+
+      format: requestDataField(
+        {
+          type: WidgetType.FORM_FIELD,
+          fieldType: FieldDataType.SELECT,
+          label: "app.api.system.help.list.fields.format.label",
+          description: "app.api.system.help.list.fields.format.description",
+          columns: 6,
+          options: [
+            {
+              value: "tree",
+              label: "app.api.system.help.list.fields.format.options.tree",
+            },
+            {
+              value: "flat",
+              label: "app.api.system.help.list.fields.format.options.flat",
+            },
+            {
+              value: "json",
+              label: "app.api.system.help.list.fields.format.options.json",
+            },
+          ],
+        },
+        z.enum(["tree", "flat", "json"]).optional().default("tree"),
+      ),
+
+      showAliases: requestDataField(
+        {
+          type: WidgetType.FORM_FIELD,
+          fieldType: FieldDataType.BOOLEAN,
+          label: "app.api.system.help.list.fields.showAliases.label",
+          description:
+            "app.api.system.help.list.fields.showAliases.description",
+          columns: 6,
+        },
+        z.boolean().optional().default(true),
+      ),
+
+      showDescriptions: requestDataField(
+        {
+          type: WidgetType.FORM_FIELD,
+          fieldType: FieldDataType.BOOLEAN,
+          label: "app.api.system.help.list.fields.showDescriptions.label",
+          description:
+            "app.api.system.help.list.fields.showDescriptions.description",
+          columns: 6,
+        },
+        z.boolean().optional().default(true),
+      ),
+
+      // === RESPONSE FIELDS ===
+      // Note: success and totalCommands are hidden internal fields
+      // They're used for response tracking but not rendered in CLI output
+
+      commands: responseArrayField(
+        {
+          type: WidgetType.GROUPED_LIST,
+          groupBy: "category",
+          sortBy: "alias",
+          hierarchical: true,
+        },
+        objectField(
+          {
+            type: WidgetType.CONTAINER,
+            layoutType: LayoutType.HORIZONTAL,
+          },
+          { response: true },
+          {
+            alias: responseField(
+              {
+                type: WidgetType.TEXT,
+                content:
+                  "app.api.system.help.list.fields.commands.alias" as const,
+              },
+              z.string(),
+            ),
+            message: responseField(
+              {
+                type: WidgetType.TEXT,
+                content:
+                  "app.api.system.help.list.fields.commands.message" as const,
+              },
+              z.string(),
+            ),
+            description: responseField(
+              {
+                type: WidgetType.TEXT,
+                content:
+                  "app.api.system.help.list.fields.commands.description" as const,
+              },
+              z.string().optional(),
+            ),
+            category: responseField(
+              {
+                type: WidgetType.TEXT,
+                content:
+                  "app.api.system.help.list.fields.commands.category" as const,
+              },
+              z.string(),
+            ),
+            aliases: responseField(
+              {
+                type: WidgetType.TEXT,
+                content:
+                  "app.api.system.help.list.fields.commands.aliases" as const,
+              },
+              z.string().optional(),
+            ),
+            rule: responseField(
+              {
+                type: WidgetType.TEXT,
+                content:
+                  "app.api.system.help.list.fields.commands.rule" as const,
+              },
+              z.string(),
+            ),
+          },
+        ),
+      ),
+    },
+  ),
+
+  // === ERROR HANDLING ===
+  errorTypes: {
+    [EndpointErrorTypes.VALIDATION_FAILED]: {
+      title: "app.api.system.help.list.post.errors.validation.title",
+      description:
+        "app.api.system.help.list.post.errors.validation.description",
+    },
+    [EndpointErrorTypes.NETWORK_ERROR]: {
+      title: "app.api.system.help.list.post.errors.network.title",
+      description: "app.api.system.help.list.post.errors.network.description",
+    },
+    [EndpointErrorTypes.UNAUTHORIZED]: {
+      title: "app.api.system.help.list.post.errors.unauthorized.title",
+      description:
+        "app.api.system.help.list.post.errors.unauthorized.description",
+    },
+    [EndpointErrorTypes.FORBIDDEN]: {
+      title: "app.api.system.help.list.post.errors.forbidden.title",
+      description: "app.api.system.help.list.post.errors.forbidden.description",
+    },
+    [EndpointErrorTypes.NOT_FOUND]: {
+      title: "app.api.system.help.list.post.errors.notFound.title",
+      description: "app.api.system.help.list.post.errors.notFound.description",
+    },
+    [EndpointErrorTypes.SERVER_ERROR]: {
+      title: "app.api.system.help.list.post.errors.server.title",
+      description: "app.api.system.help.list.post.errors.server.description",
+    },
+    [EndpointErrorTypes.UNKNOWN_ERROR]: {
+      title: "app.api.system.help.list.post.errors.unknown.title",
+      description: "app.api.system.help.list.post.errors.unknown.description",
+    },
+    [EndpointErrorTypes.UNSAVED_CHANGES]: {
+      title: "app.api.system.help.list.post.errors.server.title",
+      description: "app.api.system.help.list.post.errors.server.description",
+    },
+    [EndpointErrorTypes.CONFLICT]: {
+      title: "app.api.system.help.list.post.errors.conflict.title",
+      description: "app.api.system.help.list.post.errors.conflict.description",
+    },
+  },
+
+  // === SUCCESS HANDLING ===
+  successTypes: {
+    title: "app.api.system.help.list.post.success.title",
+    description: "app.api.system.help.list.post.success.description",
+  },
+
+  // === EXAMPLES ===
+  examples: {
+    urlPathParams: undefined,
+    requests: {
+      default: {
+        format: "tree",
+        showAliases: true,
+        showDescriptions: true,
+      },
+      treeFormat: {
+        format: "tree",
+        showAliases: true,
+        showDescriptions: true,
+      },
+      flatFormat: {
+        format: "flat",
+        showAliases: true,
+        showDescriptions: false,
+      },
+      jsonFormat: {
+        format: "json",
+        showAliases: true,
+        showDescriptions: true,
+      },
+      byCategory: {
+        category: "system",
+        format: "tree",
+        showAliases: true,
+        showDescriptions: true,
+      },
+    },
+    responses: {
+      default: {
+        commands: [
+          {
+            alias: "check",
+            message: "Run comprehensive code quality checks",
+            category: "system",
+            description: "Run comprehensive code quality checks",
+            aliases: "check, c",
+            rule: "check",
+          },
+          {
+            alias: "db:ping",
+            message: "Check database connectivity",
+            category: "database",
+            description: "Check database connectivity",
+            aliases: "ping, db:ping",
+            rule: "db:ping",
+          },
+          {
+            alias: "lead:create",
+            message: "Create a new lead",
+            category: "leads",
+            description: "Create a new lead",
+            aliases: "lead:create",
+            rule: "lead:create",
+          },
+        ],
+      },
+      treeFormat: {
+        commands: [
+          {
+            alias: "check",
+            message: "check",
+            category: "system",
+            description: "Run comprehensive code quality checks",
+            aliases: "check, c",
+            rule: "check",
+          },
+          {
+            alias: "db:migrate",
+            message: "db:migrate",
+            category: "system",
+            description: "Run database migrations",
+            aliases: "migrate",
+            rule: "db:migrate",
+          },
+        ],
+      },
+      flatFormat: {
+        commands: [
+          {
+            alias: "check",
+            message: "check",
+            category: "system",
+            aliases: "check, c",
+            rule: "check",
+          },
+          {
+            alias: "db:migrate",
+            message: "db:migrate",
+            category: "system",
+            aliases: "migrate",
+            rule: "db:migrate",
+          },
+        ],
+      },
+      jsonFormat: {
+        commands: [
+          {
+            alias: "check",
+            message: "check",
+            category: "system",
+            description: "Run comprehensive code quality checks",
+            aliases: "check, c",
+            rule: "check",
+          },
+        ],
+      },
+      byCategory: {
+        commands: [
+          {
+            alias: "check",
+            message: "check",
+            category: "system",
+            description: "Run comprehensive code quality checks",
+            aliases: "check, c",
+            rule: "check",
+          },
+          {
+            alias: "db:ping",
+            message: "db:ping",
+            category: "system",
+            description: "Check database connectivity",
+            aliases: "ping, db:ping",
+            rule: "db:ping",
+          },
+        ],
+      },
+    },
+  },
+});
+
+export type HelpListRequestInput = typeof POST.types.RequestInput;
+export type HelpListRequestOutput = typeof POST.types.RequestOutput;
+export type HelpListResponseInput = typeof POST.types.ResponseInput;
+export type HelpListResponseOutput = typeof POST.types.ResponseOutput;
+
+const endpoints = { POST };
+export default endpoints;

package/src/app/api/[locale]/system/help/list/repository.ts

@@ -0,0 +1,110 @@
+/**
+ * Help List Repository
+ * Discovers and lists all available CLI commands with their metadata
+ * Uses shared help service for unified command discovery
+ */
+
+import type { ResponseType } from "next-vibe/shared/types/response.schema";
+import {
+  ErrorResponseTypes,
+  fail,
+  success,
+} from "next-vibe/shared/types/response.schema";
+import { parseError } from "next-vibe/shared/utils";
+
+import type { JwtPayloadType } from "@/app/api/[locale]/user/auth/types";
+import type { CountryLanguage } from "@/i18n/core/config";
+
+import { definitionsRegistry } from "../../unified-interface/shared/endpoints/definitions/registry";
+import type { EndpointLogger } from "../../unified-interface/shared/logger/endpoint";
+import type { Platform } from "../../unified-interface/shared/types/platform";
+import { getTranslatorFromEndpoint } from "../../unified-interface/shared/widgets/utils/field-helpers";
+import type {
+  HelpListRequestOutput,
+  HelpListResponseOutput,
+} from "./definition";
+
+/**
+ * Help List Repository
+ */
+class HelpListRepository {
+  /**
+   * Execute the help list command
+   */
+  execute(
+    data: HelpListRequestOutput,
+    user: JwtPayloadType,
+    locale: CountryLanguage,
+    logger: EndpointLogger,
+    platform: Platform,
+  ): ResponseType<HelpListResponseOutput> {
+    logger.info("Discovering available commands");
+
+    try {
+      // Use unified endpoint listing service (filtered by user permissions from JWT)
+      const endpoints = definitionsRegistry.getEndpointsForUser(
+        platform,
+        user,
+        logger,
+      );
+
+      // Sort endpoints by category and toolName
+      const sortedEndpoints = endpoints.toSorted((a, b) => {
+        const catA = a.category || "";
+        const catB = b.category || "";
+        const catCompare = catA.localeCompare(catB);
+        if (catCompare !== 0) {
+          return catCompare;
+        }
+        const toolNameA = a.path.join("_");
+        const toolNameB = b.path.join("_");
+        return toolNameA.localeCompare(toolNameB);
+      });
+
+      // Format commands for API response
+      const formattedCommands = sortedEndpoints.map((ep) => {
+        const { t } = getTranslatorFromEndpoint(ep)(locale);
+
+        const toolName = ep.path.join("_");
+        const translatedDescription =
+          data.showDescriptions && ep.description
+            ? t(ep.description)
+            : toolName;
+        return {
+          alias: toolName,
+          message: translatedDescription,
+          description:
+            data.showDescriptions && ep.description
+              ? translatedDescription
+              : undefined,
+          category: ep.category ? t(ep.category) : "",
+          aliases:
+            data.showAliases && ep.aliases ? ep.aliases.join(", ") : undefined,
+          // Add display name for GROUPED_LIST
+          rule: toolName,
+        };
+      });
+
+      logger.info("Command discovery completed", {
+        totalCommands: formattedCommands.length,
+        filteredBy: data.category || "none",
+      });
+
+      const response: HelpListResponseOutput = {
+        commands: formattedCommands,
+      };
+
+      return success(response);
+    } catch (error) {
+      const parsedError = parseError(error);
+      logger.error("Failed to discover commands", parsedError);
+      return fail({
+        message: "app.api.system.help.list.post.errors.server.title",
+        errorType: ErrorResponseTypes.INTERNAL_ERROR,
+        messageParams: { error: parsedError.message },
+      });
+    }
+  }
+}
+
+export const helpListRepository = new HelpListRepository();

package/src/app/api/[locale]/system/help/list/route.ts

@@ -0,0 +1,21 @@
+/**
+ * Help List Route Handler
+ * Handles POST requests for listing all available CLI commands
+ */
+
+import "server-only";
+
+import { endpointsHandler } from "@/app/api/[locale]/system/unified-interface/shared/endpoints/route/multi";
+import { Methods } from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+
+import helpListEndpoints from "./definition";
+import { helpListRepository } from "./repository";
+
+export const { POST, tools } = endpointsHandler({
+  endpoint: helpListEndpoints,
+  [Methods.POST]: {
+    handler: ({ data, user, locale, logger, platform }) => {
+      return helpListRepository.execute(data, user, locale, logger, platform);
+    },
+  },
+});