@struggler/cli 1.0.13 → 1.0.15

package/Makefile

@@ -13,7 +13,7 @@ JSON ?=
 SKIP_INIT ?=
 SKIP_REFRESH ?=
 
-.PHONY: help install reinstall link unlink init upload refresh deploy add-version example-upload test
+.PHONY: help install reinstall link unlink init upload refresh deploy add-version example-upload test completion-install
 
 help:
 	@echo "Available targets:"
@@ -28,6 +28,7 @@ help:
 	@echo "  make add-version                Run the package version bump script"
 	@echo "  make example-upload             Upload the sample test/dist3 directory"
 	@echo "  make test                       Run the automated test suite"
+	@echo "  make completion-install         Install zsh completion (adds to ~/.zshrc)"
 	@echo ""
 	@echo "Variables:"
 	@echo "  CONFIG=$(CONFIG)"
@@ -58,6 +59,8 @@ link:
 	@hash -r
 	@which struggler-cli || true
 	@struggler-cli -v || true
+	@echo ""
+	@$(NODE) $(CLI_ENTRY) completion install || true
 
 unlink:
 	@$(PNPM) unlink --global @struggler/cli || true
@@ -84,3 +87,19 @@ example-upload:
 
 test:
 	$(PNPM) test
+
+completion-install:
+	@FPATH_DIR="$${HOME}/.zsh/completions"; \
+	mkdir -p "$$FPATH_DIR"; \
+	$(NODE) $(CLI_ENTRY) completion zsh > "$$FPATH_DIR/_struggler-cli"; \
+	echo "  ✓  zsh completion installed: $$FPATH_DIR/_struggler-cli"; \
+	if ! grep -q "$$FPATH_DIR" "$${HOME}/.zshrc" 2>/dev/null; then \
+		echo "" >> "$${HOME}/.zshrc"; \
+		echo "# struggler-cli zsh completion" >> "$${HOME}/.zshrc"; \
+		echo "fpath=($$FPATH_DIR \$$fpath)" >> "$${HOME}/.zshrc"; \
+		echo "autoload -Uz compinit && compinit" >> "$${HOME}/.zshrc"; \
+		echo "  ✓  added fpath to ~/.zshrc"; \
+	else \
+		echo "  ·  fpath already in ~/.zshrc, skipped"; \
+	fi; \
+	echo "  →  run: source ~/.zshrc"

package/README.md

@@ -185,6 +185,39 @@ struggler-cli deploy -d ./dist --json --dry-run
 - Avoid spaces in profile names; use `prod`, `staging`, `dev`.
 - When scripting, quote paths: `--config-dir "./command"`.
 
+## Shell completion
+
+Enable tab completion for subcommands, flags, and profile names.
+
+### zsh (recommended)
+
+One-liner install:
+
+```bash
+make completion-install
+source ~/.zshrc
+```
+
+Or manually:
+
+```bash
+mkdir -p ~/.zsh/completions
+struggler-cli completion zsh > ~/.zsh/completions/_struggler-cli
+# add to ~/.zshrc if not already present:
+echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### bash
+
+```bash
+struggler-cli completion bash >> ~/.bash_profile
+source ~/.bash_profile
+```
+
+After installation, `struggler-cli <TAB>` completes subcommands, flags, and `profile use <TAB>` completes your profile names.
+
 ## Makefile shortcuts
 
 ```bash

package/command/completion.js

@@ -0,0 +1,260 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { listProfiles } = require('../lib/profile');
+
+// Completion scripts are built from string arrays to avoid
+// conflicts between JS template literals and shell variable syntax like ${(f)...}.
+
+function zshScript() {
+    const lines = [
+        '#compdef struggler-cli',
+        '',
+        '_struggler_cli() {',
+        '  local context state line',
+        '  typeset -A opt_args',
+        '',
+        '  _arguments -C \\',
+        "    '(-v --version)'{-v,--version}'[show version]' \\",
+        "    '(-h --help)'{-h,--help}'[show help]' \\",
+        "    '(-c --config)'{-c,--config}'[qiniu config: profile name or file path]:config:' \\",
+        "    '--config-dir[meta config directory]:dir:_files -/' \\",
+        "    '(-d --dir)'{-d,--dir}'[upload source directory]:dir:_files -/' \\",
+        "    '--dry-run[preview without writing or calling qiniu]' \\",
+        "    '--concurrency[upload concurrency]:number:(1 2 3 4 5 8 10)' \\",
+        "    '--exclude[exclude glob pattern]:pattern:' \\",
+        "    '--ignore-file[custom ignore file]:file:_files' \\",
+        "    '--manifest[write result to manifest json]:file:_files' \\",
+        "    '--json[machine-readable json output]' \\",
+        "    '--skip-init[skip init step in deploy]' \\",
+        "    '--skip-refresh[skip refresh step in deploy]' \\",
+        "    '--no-cache[force re-upload all files]' \\",
+        "    '--lang[ui language]:lang:(zh en)' \\",
+        "    '1: :_struggler_cli_cmds' \\",
+        "    '*::arg:->args'",
+        '',
+        '  case $state in',
+        '    args)',
+        '      case $line[1] in',
+        '        profile)',
+        '          _struggler_cli_profile',
+        '          ;;',
+        '        completion)',
+        "          _arguments '1:shell:(zsh bash)'",
+        '          ;;',
+        '        init|upload|refresh|deploy)',
+        "          _message 'no more subcommands'",
+        '          ;;',
+        '      esac',
+        '      ;;',
+        '  esac',
+        '}',
+        '',
+        '_struggler_cli_cmds() {',
+        '  local cmds',
+        '  cmds=(',
+        "    'init:generate versioned upload config'",
+        "    'upload:upload build files to qiniu'",
+        "    'refresh:refresh qiniu cdn urls'",
+        "    'deploy:run init + upload + refresh'",
+        "    'profile:manage qiniu credential profiles'",
+        "    'completion:output shell completion script'",
+        '  )',
+        "  _describe 'command' cmds",
+        '}',
+        '',
+        '_struggler_cli_profile() {',
+        '  local subcmds',
+        '  subcmds=(',
+        "    'list:list all profiles'",
+        "    'use:set active profile'",
+        "    'current:show active profile'",
+        "    'add:create profile from template'",
+        "    'import:import profile from file'",
+        '  )',
+        '',
+        '  if (( CURRENT == 2 )); then',
+        "    _describe 'profile subcommand' subcmds",
+        '    return',
+        '  fi',
+        '',
+        '  case $words[2] in',
+        '    use)',
+        // Use a dedicated CLI helper to list profiles, avoiding nested quote hell
+        '      local profiles',
+        '      profiles=($(struggler-cli completion --list-profiles 2>/dev/null))',
+        '      if [[ ${#profiles[@]} -gt 0 ]]; then',
+        "        _describe 'profile' profiles",
+        '      else',
+        "        _message 'profile name'",
+        '      fi',
+        '      ;;',
+        '    import)',
+        "      (( CURRENT == 3 )) && _message 'profile name'",
+        '      (( CURRENT == 4 )) && _files',
+        '      ;;',
+        '  esac',
+        '}',
+        '',
+        '_struggler_cli',
+        '',
+    ];
+    return lines.join('\n');
+}
+
+function bashScript() {
+    const lines = [
+        '# bash completion for struggler-cli',
+        '# source this file or put in ~/.bash_completion.d/struggler-cli',
+        '',
+        '_struggler_cli_completion() {',
+        '  local cur prev words cword',
+        '  _init_completion 2>/dev/null || {',
+        '    COMPREPLY=()',
+        '    cur="${COMP_WORDS[COMP_CWORD]}"',
+        '    prev="${COMP_WORDS[COMP_CWORD-1]}"',
+        '  }',
+        '',
+        '  local cmds="init upload refresh deploy profile completion"',
+        '  local profile_cmds="list use current add import"',
+        '  local global_opts="-v --version -h --help -c --config --config-dir -d --dir --dry-run --concurrency --exclude --ignore-file --manifest --json --skip-init --skip-refresh --no-cache --lang"',
+        '',
+        '  if [[ ${COMP_CWORD} -eq 1 ]]; then',
+        '    COMPREPLY=($(compgen -W "${cmds}" -- "${cur}"))',
+        '    return',
+        '  fi',
+        '',
+        '  case "${COMP_WORDS[1]}" in',
+        '    profile)',
+        '      if [[ ${COMP_CWORD} -eq 2 ]]; then',
+        '        COMPREPLY=($(compgen -W "${profile_cmds}" -- "${cur}"))',
+        '        return',
+        '      fi',
+        '      if [[ "${COMP_WORDS[2]}" == "use" && ${COMP_CWORD} -eq 3 ]]; then',
+        '        local profiles',
+        '        profiles=$(struggler-cli completion --list-profiles 2>/dev/null)',
+        '        COMPREPLY=($(compgen -W "${profiles}" -- "${cur}"))',
+        '        return',
+        '      fi',
+        '      ;;',
+        '    completion)',
+        '      if [[ ${COMP_CWORD} -eq 2 ]]; then',
+        '        COMPREPLY=($(compgen -W "zsh bash" -- "${cur}"))',
+        '        return',
+        '      fi',
+        '      ;;',
+        '    init|upload|refresh|deploy)',
+        '      COMPREPLY=($(compgen -W "${global_opts}" -- "${cur}"))',
+        '      return',
+        '      ;;',
+        '  esac',
+        '}',
+        '',
+        'complete -F _struggler_cli_completion struggler-cli',
+        '',
+    ];
+    return lines.join('\n');
+}
+
+function detectShell() {
+    const shellBin = process.env.SHELL || '';
+    if (shellBin.endsWith('zsh')) return 'zsh';
+    if (shellBin.endsWith('bash')) return 'bash';
+    return null;
+}
+
+function installZsh(script) {
+    const dir = path.join(os.homedir(), '.zsh', 'completions');
+    const file = path.join(dir, '_struggler-cli');
+    const rcFile = path.join(os.homedir(), '.zshrc');
+
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, script, 'utf8');
+    console.log('  \u2713  zsh completion installed: ' + file);
+
+    let rc = '';
+    try { rc = fs.readFileSync(rcFile, 'utf8'); } catch { /* new file */ }
+
+    const fpathLine = 'fpath=(' + dir + ' $fpath)';
+    const compLine = 'autoload -Uz compinit && compinit';
+    const marker = '# struggler-cli completion';
+
+    if (!rc.includes(marker)) {
+        const addition = '\n' + marker + '\n' + fpathLine + '\n' + compLine + '\n';
+        fs.appendFileSync(rcFile, addition, 'utf8');
+        console.log('  \u2713  added fpath + compinit to ~/.zshrc');
+    } else {
+        console.log('  \u00b7  ~/.zshrc already configured, skipped');
+    }
+    console.log('  \u2192  run: source ~/.zshrc');
+}
+
+function installBash(script) {
+    const dir = path.join(os.homedir(), '.bash_completion.d');
+    const file = path.join(dir, 'struggler-cli');
+    const rcFile = path.join(os.homedir(), '.bash_profile');
+
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, script, 'utf8');
+    console.log('  \u2713  bash completion installed: ' + file);
+
+    let rc = '';
+    try { rc = fs.readFileSync(rcFile, 'utf8'); } catch { /* new file */ }
+
+    const marker = '# struggler-cli completion';
+    if (!rc.includes(marker)) {
+        const addition = '\n' + marker + '\n[ -f ' + file + ' ] && source ' + file + '\n';
+        fs.appendFileSync(rcFile, addition, 'utf8');
+        console.log('  \u2713  added source line to ~/.bash_profile');
+    } else {
+        console.log('  \u00b7  ~/.bash_profile already configured, skipped');
+    }
+    console.log('  \u2192  run: source ~/.bash_profile');
+}
+
+function installAction(_options) {
+    const shell = detectShell();
+    if (!shell) {
+        process.stderr.write('Cannot detect shell from $SHELL. Run manually:\n');
+        process.stderr.write('  struggler-cli completion zsh  > ~/.zsh/completions/_struggler-cli\n');
+        process.stderr.write('  struggler-cli completion bash > ~/.bash_completion.d/struggler-cli\n');
+        process.exitCode = 1;
+        return;
+    }
+    console.log('  detected shell: ' + shell);
+    if (shell === 'zsh') {
+        installZsh(zshScript());
+    } else {
+        installBash(bashScript());
+    }
+}
+
+function completionAction(shell, options) {
+    // Internal helper: list profile names for shell completion scripts
+    if (options && options.listProfiles) {
+        try {
+            listProfiles().forEach((name) => process.stdout.write(name + '\n'));
+        } catch {
+            // silently fail; completion scripts handle empty output
+        }
+        return;
+    }
+
+    // Auto-install to current shell
+    if (shell === 'install' || (options && options.install)) {
+        installAction(options);
+        return;
+    }
+
+    const s = (shell || '').toLowerCase();
+    if (s === 'zsh') {
+        process.stdout.write(zshScript());
+    } else if (s === 'bash') {
+        process.stdout.write(bashScript());
+    } else {
+        process.stderr.write('Usage: struggler-cli completion <zsh|bash|install>\n');
+        process.exitCode = 1;
+    }
+}
+
+module.exports = completionAction;

package/command/index.js

@@ -3,9 +3,11 @@ var upload = require('./upload');
 var refresh = require('./refresh');
 var deploy = require('./deploy');
 var profile = require('./profile');
+var completion = require('./completion');
 
 exports.init = init;
 exports.upload = upload;
 exports.refresh = refresh;
 exports.deploy = deploy;
 exports.profile = profile;
+exports.completion = completion;

package/command/profile.js

@@ -9,7 +9,7 @@ const {
     getProfilePath,
     getProfilesDir,
 } = require('../lib/profile');
-const { printMessage } = require('../lib/output');
+const { printMessage, printJson, shouldUseJson } = require('../lib/output');
 const { getLocale } = require('../lib/i18n');
 
 const TEMPLATE_PATH = path.resolve(__dirname, '../def/qiniu.json');
@@ -34,7 +34,11 @@ function listAction(options) {
     if (current) {
         printMessage(options, chalk.dim(messages.profileListCurrentHint));
     }
-    return { profiles, current };
+    const result = { profiles, current };
+    if (shouldUseJson(options)) {
+        printJson(result);
+    }
+    return result;
 }
 
 function useAction(name, options) {

package/index.js

@@ -9,14 +9,15 @@ const { resolveLang, getLocale } = require("./lib/i18n")
 const lang = resolveLang(process.argv)
 const locale = getLocale(lang)
 const isJsonMode = process.argv.includes("--json")
+const isVersionMode = process.argv.includes("-v") || process.argv.includes("--version")
 
-// 清除命令行
-if (!shouldUseJson({ json: isJsonMode })) {
-	clear()
-}
+// 只有在没有执行具体子命令时（即展示根 help）才显示 logo
+const KNOWN_CMDS = new Set(['init', 'upload', 'refresh', 'deploy', 'profile', 'completion'])
+const hasSubCmd = process.argv.slice(2).some((a) => KNOWN_CMDS.has(a))
+const showLogo = !isJsonMode && !hasSubCmd && !isVersionMode
 
-// 输出Logo
-if (!isJsonMode) {
+if (showLogo) {
+	clear()
 	console.log(require('./lib/logo') + '\n')
 }
 
@@ -125,7 +126,16 @@ profileCmd
 		command.profile.import(name, file, program.opts())
 	})
 
-program.addHelpCommand(true, locale.help.helpCommandDescription)
+program
+	.command("completion [shell]")
+	.description(locale.commands.completion)
+	.option("--list-profiles", "list profile names (used by shell completion)")
+	.addHelpText('after', '\nshell: zsh | bash | install (auto-detect and install)')
+	.action((shell, cmdOpts) => {
+		command.completion(shell, { ...program.opts(), ...cmdOpts })
+	})
+
+program.addHelpCommand(false)
 
 program.parseAsync().catch(error => {
 	if (isJsonMode) {

package/lib/i18n.js

@@ -72,6 +72,7 @@ const LANGUAGES = {
             profileCurrent: '显示当前 profile',
             profileAdd: '从模版新建 profile',
             profileImport: '从已有文件导入 profile',
+            completion: '输出 shell 补全脚本（zsh / bash），或 install 自动安装到当前 shell',
         },
         help: {
             helpCommandDescription: '显示指定命令的帮助信息',
@@ -161,6 +162,7 @@ const LANGUAGES = {
             profileCurrent: 'Show active profile',
             profileAdd: 'Create profile from template',
             profileImport: 'Import profile from file',
+            completion: 'Output shell completion script (zsh / bash), or "install" to auto-install for current shell',
         },
         help: {
             helpCommandDescription: 'display help for command',

package/package.json

@@ -1,11 +1,12 @@
 {
 	"name": "@struggler/cli",
-	"version": "1.0.13",
+	"version": "1.0.15",
 	"description": "CLI to Upload vite packaged files to Qiniu Cloud OSS.",
 	"main": "index.js",
 	"scripts": {
 		"add-version": "node ./command/addVersion.js",
-		"test": "node --test"
+		"test": "node --test",
+		"postinstall": "node ./scripts/postinstall.js"
 	},
 	"bin": {
 		"struggler-cli": "./index.js"

package/scripts/postinstall.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Only print the hint during global installs; skip in CI / local dev installs.
+const isGlobal = process.env.npm_config_global === 'true';
+const isCI = process.env.CI || process.env.CONTINUOUS_INTEGRATION;
+
+if (!isGlobal || isCI) process.exit(0);
+
+const shell = (process.env.SHELL || '').split('/').pop();
+const supported = shell === 'zsh' || shell === 'bash';
+
+console.log('');
+console.log('  \u2728  struggler-cli installed!');
+if (supported) {
+    console.log('  \u2192  Enable tab completion (one-time setup):');
+    console.log('       struggler-cli completion install');
+} else {
+    console.log('  \u2192  Enable tab completion: struggler-cli completion <zsh|bash|install>');
+}
+console.log('');