@git.zone/cli 2.13.15 → 2.14.0

package/ts/mod_standard/index.ts

@@ -1,91 +1,224 @@
 /* -----------------------------------------------
  * executes as standard  task
  * ----------------------------------------------- */
-import * as plugins from './mod.plugins.js';
-import * as paths from '../paths.js';
+import * as plugins from "./mod.plugins.js";
+import * as paths from "../paths.js";
+import type { ICliMode } from "../helpers.climode.js";
+import { getCliMode, printJson } from "../helpers.climode.js";
 
-import { logger } from '../gitzone.logging.js';
+import { logger } from "../gitzone.logging.js";
 
-export let run = async () => {
-  console.log('');
-  console.log('╭─────────────────────────────────────────────────────────────╮');
-  console.log('│  gitzone - Development Workflow CLI                         │');
-  console.log('╰─────────────────────────────────────────────────────────────╯');
-  console.log('');
+type ICommandHelpSummary = {
+  name: string;
+  description: string;
+};
+
+const commandSummaries: ICommandHelpSummary[] = [
+  {
+    name: "commit",
+    description:
+      "Create semantic commits or generate read-only commit recommendations",
+  },
+  { name: "format", description: "Plan or apply project formatting changes" },
+  { name: "config", description: "Read and change .smartconfig.json settings" },
+  { name: "services", description: "Manage or configure development services" },
+  { name: "template", description: "Create a project from a template" },
+  { name: "open", description: "Open project assets and CI pages" },
+  { name: "docker", description: "Run Docker-related maintenance tasks" },
+  {
+    name: "deprecate",
+    description: "Deprecate npm packages across registries",
+  },
+  { name: "meta", description: "Run meta-repository commands" },
+  { name: "start", description: "Prepare a project for local work" },
+  { name: "helpers", description: "Run helper utilities" },
+];
+
+export let run = async (argvArg: any = {}) => {
+  const mode = await getCliMode(argvArg);
+  const requestedCommandHelp =
+    argvArg._?.[0] === "help" ? argvArg._?.[1] : undefined;
+
+  if (mode.help || requestedCommandHelp) {
+    await showHelp(mode, requestedCommandHelp);
+    return;
+  }
+
+  if (!mode.interactive) {
+    await showHelp(mode);
+    return;
+  }
+
+  console.log("");
+  console.log(
+    "╭─────────────────────────────────────────────────────────────╮",
+  );
+  console.log(
+    "│  gitzone - Development Workflow CLI                         │",
+  );
+  console.log(
+    "╰─────────────────────────────────────────────────────────────╯",
+  );
+  console.log("");
 
   const interactInstance = new plugins.smartinteract.SmartInteract();
   const response = await interactInstance.askQuestion({
-    type: 'list',
-    name: 'action',
-    message: 'What would you like to do?',
-    default: 'commit',
+    type: "list",
+    name: "action",
+    message: "What would you like to do?",
+    default: "commit",
     choices: [
-      { name: 'Commit changes (semantic versioning)', value: 'commit' },
-      { name: 'Format project files', value: 'format' },
-      { name: 'Configure release settings', value: 'config' },
-      { name: 'Create from template', value: 'template' },
-      { name: 'Manage dev services (MongoDB, S3)', value: 'services' },
-      { name: 'Open project assets', value: 'open' },
-      { name: 'Show help', value: 'help' },
+      { name: "Commit changes (semantic versioning)", value: "commit" },
+      { name: "Format project files", value: "format" },
+      { name: "Configure release settings", value: "config" },
+      { name: "Create from template", value: "template" },
+      { name: "Manage dev services (MongoDB, S3)", value: "services" },
+      { name: "Open project assets", value: "open" },
+      { name: "Show help", value: "help" },
     ],
   });
 
   const action = (response as any).value;
 
   switch (action) {
-    case 'commit': {
-      const modCommit = await import('../mod_commit/index.js');
-      await modCommit.run({ _: ['commit'] });
+    case "commit": {
+      const modCommit = await import("../mod_commit/index.js");
+      await modCommit.run({ _: ["commit"] });
       break;
     }
-    case 'format': {
-      const modFormat = await import('../mod_format/index.js');
+    case "format": {
+      const modFormat = await import("../mod_format/index.js");
       await modFormat.run({ interactive: true });
       break;
     }
-    case 'config': {
-      const modConfig = await import('../mod_config/index.js');
-      await modConfig.run({ _: ['config'] });
+    case "config": {
+      const modConfig = await import("../mod_config/index.js");
+      await modConfig.run({ _: ["config"] });
       break;
     }
-    case 'template': {
-      const modTemplate = await import('../mod_template/index.js');
-      await modTemplate.run({ _: ['template'] });
+    case "template": {
+      const modTemplate = await import("../mod_template/index.js");
+      await modTemplate.run({ _: ["template"] });
       break;
     }
-    case 'services': {
-      const modServices = await import('../mod_services/index.js');
-      await modServices.run({ _: ['services'] });
+    case "services": {
+      const modServices = await import("../mod_services/index.js");
+      await modServices.run({ _: ["services"] });
       break;
     }
-    case 'open': {
-      const modOpen = await import('../mod_open/index.js');
-      await modOpen.run({ _: ['open'] });
+    case "open": {
+      const modOpen = await import("../mod_open/index.js");
+      await modOpen.run({ _: ["open"] });
       break;
     }
-    case 'help':
-      showHelp();
+    case "help":
+      await showHelp(mode);
       break;
   }
 };
 
-function showHelp(): void {
-  console.log('');
-  console.log('Usage: gitzone <command> [options]');
-  console.log('');
-  console.log('Commands:');
-  console.log('  commit      Create a semantic commit with versioning');
-  console.log('  format      Format and standardize project files');
-  console.log('  config      Manage release registry configuration');
-  console.log('  template    Create a new project from template');
-  console.log('  services    Manage dev services (MongoDB, S3/MinIO)');
-  console.log('  open        Open project assets (GitLab, npm, etc.)');
-  console.log('  docker      Docker-related operations');
-  console.log('  deprecate   Deprecate a package on npm');
-  console.log('  meta        Run meta commands');
-  console.log('  start       Start working on a project');
-  console.log('  helpers     Run helper utilities');
-  console.log('');
-  console.log('Run gitzone <command> --help for more information on a command.');
-  console.log('');
+export async function showHelp(
+  mode: ICliMode,
+  commandName?: string,
+): Promise<void> {
+  if (commandName) {
+    const handled = await showCommandHelp(commandName, mode);
+    if (handled) {
+      return;
+    }
+  }
+
+  if (mode.json) {
+    printJson({
+      name: "gitzone",
+      usage: "gitzone <command> [options]",
+      commands: commandSummaries,
+      globalFlags: [
+        { flag: "--help, -h", description: "Show help output" },
+        {
+          flag: "--json",
+          description: "Emit machine-readable JSON when supported",
+        },
+        {
+          flag: "--plain",
+          description: "Use plain text output when supported",
+        },
+        {
+          flag: "--agent",
+          description: "Prefer non-interactive machine-friendly output",
+        },
+        {
+          flag: "--no-interactive",
+          description: "Disable prompts and interactive menus",
+        },
+        {
+          flag: "--no-check-updates",
+          description: "Skip the update check banner",
+        },
+      ],
+    });
+    return;
+  }
+
+  console.log("");
+  console.log("Usage: gitzone <command> [options]");
+  console.log("");
+  console.log("Commands:");
+  for (const commandSummary of commandSummaries) {
+    console.log(
+      `  ${commandSummary.name.padEnd(11)} ${commandSummary.description}`,
+    );
+  }
+  console.log("");
+  console.log("Global flags:");
+  console.log("  --help, -h            Show help output");
+  console.log(
+    "  --json                Emit machine-readable JSON when supported",
+  );
+  console.log("  --plain               Use plain text output when supported");
+  console.log(
+    "  --agent               Prefer non-interactive machine-friendly output",
+  );
+  console.log("  --no-interactive      Disable prompts and interactive menus");
+  console.log("  --no-check-updates    Skip the update check banner");
+  console.log("");
+  console.log("Examples:");
+  console.log("  gitzone help commit");
+  console.log("  gitzone config show --json");
+  console.log("  gitzone commit recommend --json");
+  console.log("  gitzone format plan --json");
+  console.log("  gitzone services set mongodb,minio");
+  console.log("");
+  console.log("Run gitzone <command> --help for command-specific usage.");
+  console.log("");
+}
+
+async function showCommandHelp(
+  commandName: string,
+  mode: ICliMode,
+): Promise<boolean> {
+  switch (commandName) {
+    case "commit": {
+      const modCommit = await import("../mod_commit/index.js");
+      modCommit.showHelp(mode);
+      return true;
+    }
+    case "config": {
+      const modConfig = await import("../mod_config/index.js");
+      modConfig.showHelp(mode);
+      return true;
+    }
+    case "format": {
+      const modFormat = await import("../mod_format/index.js");
+      modFormat.showHelp(mode);
+      return true;
+    }
+    case "services": {
+      const modServices = await import("../mod_services/index.js");
+      modServices.showHelp(mode);
+      return true;
+    }
+    default:
+      return false;
+  }
 }