@crustjs/plugins 0.0.2

package/README.md

@@ -0,0 +1,43 @@
+# @crustjs/plugins
+
+Official plugins for the [Crust](https://crust.cyanlabs.co) CLI framework.
+
+## Install
+
+```sh
+bun add @crustjs/plugins
+```
+
+## Plugins
+
+| Plugin | Description |
+| --- | --- |
+| `helpPlugin()` | Adds `--help` / `-h` flag and auto-generates help text |
+| `versionPlugin(version)` | Adds `--version` / `-v` flag |
+| `autoCompletePlugin(options?)` | Shell autocompletion support |
+
+## Usage
+
+```ts
+import { defineCommand, runMain } from "@crustjs/core";
+import { helpPlugin, versionPlugin, autoCompletePlugin } from "@crustjs/plugins";
+
+const main = defineCommand({
+  meta: { name: "my-cli", description: "My CLI tool" },
+  run() {
+    console.log("Hello!");
+  },
+});
+
+runMain(main, {
+  plugins: [versionPlugin("1.0.0"), autoCompletePlugin(), helpPlugin()],
+});
+```
+
+## Documentation
+
+See the full docs at [crust.cyanlabs.co](https://crust.cyanlabs.co).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { CrustPlugin } from "@crustjs/core";
+interface AutoCompletePluginOptions {
+	mode?: "error" | "help";
+}
+declare function autoCompletePlugin(options?: AutoCompletePluginOptions): CrustPlugin;
+import { AnyCommand, CrustPlugin as CrustPlugin2 } from "@crustjs/core";
+declare function renderHelp(command: AnyCommand, path: string[]): string;
+declare function helpPlugin(): CrustPlugin2;
+import { CrustPlugin as CrustPlugin3 } from "@crustjs/core";
+type VersionValue = string | (() => string);
+declare function versionPlugin(versionValue?: VersionValue): CrustPlugin3;
+export { versionPlugin, renderHelp, helpPlugin, autoCompletePlugin, VersionValue, AutoCompletePluginOptions };

package/dist/index.js

@@ -0,0 +1,233 @@
+// @bun
+// src/autocomplete.ts
+import { CrustError } from "@crustjs/core";
+
+// src/help.ts
+function formatArgToken(arg) {
+  const base = arg.variadic ? `${arg.name}...` : arg.name;
+  return arg.required ? `<${base}>` : `[${base}]`;
+}
+function formatUsage(meta, command, path) {
+  if (meta.usage)
+    return meta.usage;
+  const usageParts = [path.join(" ")];
+  if (command.subCommands && Object.keys(command.subCommands).length > 0 && !command.run) {
+    usageParts.push("<command>");
+  }
+  if (command.args) {
+    for (const arg of command.args) {
+      usageParts.push(formatArgToken(arg));
+    }
+  }
+  if (command.flags && Object.keys(command.flags).length > 0) {
+    usageParts.push("[options]");
+  }
+  return usageParts.join(" ");
+}
+function formatFlagName(name, def) {
+  if (!def.alias)
+    return `--${name}`;
+  const aliases = Array.isArray(def.alias) ? def.alias : [def.alias];
+  const shortAlias = aliases.find((alias) => alias.length === 1);
+  if (shortAlias) {
+    return `-${shortAlias}, --${name}`;
+  }
+  return `--${name}`;
+}
+function formatFlagsSection(flagsDef) {
+  if (!flagsDef || Object.keys(flagsDef).length === 0)
+    return [];
+  const lines = ["OPTIONS:"];
+  for (const [name, def] of Object.entries(flagsDef)) {
+    const rendered = formatFlagName(name, def).padEnd(18, " ");
+    lines.push(`  ${rendered}${def.description ?? ""}`.trimEnd());
+  }
+  return lines;
+}
+function formatArgsSection(command) {
+  if (!command.args || command.args.length === 0)
+    return [];
+  const lines = ["ARGS:"];
+  for (const arg of command.args) {
+    const rendered = formatArgToken(arg).padEnd(18, " ");
+    lines.push(`  ${rendered}${arg.description ?? ""}`.trimEnd());
+  }
+  return lines;
+}
+function formatCommandsSection(command) {
+  if (!command.subCommands || Object.keys(command.subCommands).length === 0) {
+    return [];
+  }
+  const lines = ["COMMANDS:"];
+  for (const [name, subCommand] of Object.entries(command.subCommands)) {
+    const rendered = name.padEnd(10, " ");
+    lines.push(`  ${rendered}${subCommand.meta.description ?? ""}`.trimEnd());
+  }
+  return lines;
+}
+function renderHelp(command, path) {
+  const lines = [];
+  lines.push(command.meta.description ? `${path.join(" ")} - ${command.meta.description}` : path.join(" "));
+  lines.push("");
+  lines.push("USAGE:");
+  lines.push(`  ${formatUsage(command.meta, command, path)}`);
+  const commandsSection = formatCommandsSection(command);
+  if (commandsSection.length > 0) {
+    lines.push("");
+    lines.push(...commandsSection);
+  }
+  const argsSection = formatArgsSection(command);
+  if (argsSection.length > 0) {
+    lines.push("");
+    lines.push(...argsSection);
+  }
+  const optionsSection = formatFlagsSection(command.flags);
+  if (optionsSection.length > 0) {
+    lines.push("");
+    lines.push(...optionsSection);
+  }
+  return lines.join(`
+`);
+}
+var helpFlagDef = {
+  type: Boolean,
+  alias: "h",
+  description: "Show help"
+};
+function injectHelpFlags(command, addFlag) {
+  addFlag(command, "help", helpFlagDef);
+  if (command.subCommands) {
+    for (const sub of Object.values(command.subCommands)) {
+      injectHelpFlags(sub, addFlag);
+    }
+  }
+}
+function helpPlugin() {
+  return {
+    name: "help",
+    setup(context, actions) {
+      injectHelpFlags(context.rootCommand, actions.addFlag);
+    },
+    async middleware(context, next) {
+      if (!context.route) {
+        await next();
+        return;
+      }
+      const routedCommand = context.route.command;
+      const shouldShowHelp = context.input?.flags.help === true;
+      if (!shouldShowHelp && routedCommand.run) {
+        await next();
+        return;
+      }
+      console.log(renderHelp(routedCommand, [...context.route.commandPath]));
+    }
+  };
+}
+
+// src/autocomplete.ts
+function levenshtein(a, b) {
+  const aLen = a.length;
+  const bLen = b.length;
+  if (aLen === 0)
+    return bLen;
+  if (bLen === 0)
+    return aLen;
+  const row = Array.from({ length: bLen + 1 }, (_, i) => i);
+  for (let i = 1;i <= aLen; i++) {
+    let prev = i;
+    for (let j = 1;j <= bLen; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(row[j] + 1, prev + 1, row[j - 1] + cost);
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[bLen] = prev;
+  }
+  return row[bLen];
+}
+function findSuggestions(input, candidates) {
+  const suggestions = [];
+  for (const candidate of candidates) {
+    if (candidate.startsWith(input) || input.startsWith(candidate)) {
+      suggestions.push({ name: candidate, distance: 0 });
+      continue;
+    }
+    const distance = levenshtein(input, candidate);
+    if (distance <= 3) {
+      suggestions.push({ name: candidate, distance });
+    }
+  }
+  suggestions.sort((a, b) => {
+    if (a.distance !== b.distance)
+      return a.distance - b.distance;
+    return a.name.localeCompare(b.name);
+  });
+  return suggestions.map((suggestion) => suggestion.name);
+}
+function autoCompletePlugin(options = {}) {
+  const mode = options.mode ?? "error";
+  return {
+    name: "autocomplete",
+    async middleware(_context, next) {
+      try {
+        await next();
+        return;
+      } catch (error) {
+        if (!(error instanceof CrustError))
+          throw error;
+        if (!error.is("COMMAND_NOT_FOUND"))
+          throw error;
+        const details = error.details;
+        const suggestions = findSuggestions(details.input, details.available);
+        let message = `Unknown command "${details.input}".`;
+        if (suggestions.length > 0) {
+          message += ` Did you mean "${suggestions[0]}"?`;
+        }
+        if (mode === "help") {
+          console.log(message);
+          console.log("");
+          console.log(renderHelp(details.parentCommand, details.commandPath));
+          return;
+        }
+        if (details.available.length > 0) {
+          message += `
+
+Available commands: ${details.available.join(", ")}`;
+        }
+        console.error(message);
+        process.exitCode = 1;
+      }
+    }
+  };
+}
+// src/version.ts
+function versionPlugin(versionValue = "0.0.0") {
+  return {
+    name: "version",
+    setup(context, actions) {
+      actions.addFlag(context.rootCommand, "version", {
+        type: Boolean,
+        alias: "v",
+        description: "Show version number"
+      });
+    },
+    async middleware(context, next) {
+      if (!context.route || context.route.command !== context.rootCommand) {
+        await next();
+        return;
+      }
+      if (!context.input?.flags.version) {
+        await next();
+        return;
+      }
+      const version = typeof versionValue === "function" ? versionValue() : versionValue;
+      console.log(`${context.rootCommand.meta.name} v${version}`);
+    }
+  };
+}
+export {
+  versionPlugin,
+  renderHelp,
+  helpPlugin,
+  autoCompletePlugin
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@crustjs/plugins",
+	"version": "0.0.2",
+	"description": "Official plugins for the Crust CLI framework",
+	"type": "module",
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/plugins"
+	},
+	"homepage": "https://crust.cyanlabs.co",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"plugin",
+		"help",
+		"version",
+		"autocomplete",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@crustjs/config": "workspace:*",
+		"@crustjs/core": "workspace:*",
+		"bunup": "catalog:"
+	},
+	"peerDependencies": {
+		"@crustjs/core": "workspace:*",
+		"typescript": "catalog:"
+	}
+}