@buildinternet/uploads 0.41.0 → 0.41.1

package/README.md

@@ -58,7 +58,12 @@ answers `did you mean: uploads meta set`. With `--json`, an unknown command
 returns `{ "error", "code": "USAGE", "didYouMean" }` on stdout.
 
 **Shell completion:** `uploads completion bash|zsh|fish` prints a script to
-stdout. Example (zsh): `uploads completion zsh > ~/.zsh/completions/_uploads`.
+stdout. Save it where your shell looks for completions, then start a new shell.
+For zsh, write the script to `~/.zsh/completions/_uploads`, then bind it at the
+end of `~/.zshrc` with `fpath=(~/.zsh/completions $fpath)` and
+`autoload -Uz _uploads && compdef _uploads uploads`. The `compdef` line matters:
+a cached `compinit -C` never rescans fpath, so the file alone can go unnoticed.
+`uploads completion --help` covers the rest.
 
 **Globals (before the command):** `--api-url`, `--token`, `--workspace` / `-w`,
 `--env-file`, `--json`, `--quiet`, `--version` / `-V`, `-h` / `--help`, `--all`

package/dist/commands/completion.js

@@ -3,8 +3,9 @@ import { ANNOTATE_FLAGS, COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_L
 import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads completion <shell>
 
-Print a shell completion script to stdout. Source it or install it so Tab
-completes commands, subcommands, and common flags.
+Print a shell completion script to stdout. Save it where your shell looks for
+completions, then start a new shell. Tab then completes commands, subcommands,
+and common flags.
 
 Shells:
   bash   Bash (complete -F)
@@ -12,16 +13,36 @@ Shells:
   fish   Fish (complete -c)
 
 Examples:
-  # zsh (Oh My Zsh / fpath)
-  uploads completion zsh > ~/.zsh/completions/_uploads
-
-  # bash
-  uploads completion bash > ~/.local/share/bash-completion/completions/uploads
-  # or for the current session:
+  # bash — for the current session:
   eval "$(uploads completion bash)"
+  # or save it:
+  uploads completion bash > ~/.local/share/bash-completion/completions/uploads
 
   # fish
   uploads completion fish > ~/.config/fish/completions/uploads.fish
+
+  # zsh — save the script:
+  uploads completion zsh > ~/.zsh/completions/_uploads
+  # then add these two lines to the END of ~/.zshrc:
+  #   fpath=(~/.zsh/completions $fpath)
+  #   autoload -Uz _uploads && compdef _uploads uploads
+
+Zsh notes:
+  Saving the file into an fpath directory is often not enough. compinit caches
+  its scan in ~/.zcompdump, and \`compinit -C\` reuses that cache instead of
+  rescanning, so it never sees the new file. Oh My Zsh and several installers
+  call compinit that way. Some plugins also rewrite fpath as they load, which
+  drops entries added before them; zsh-autocomplete is one.
+
+  The \`compdef\` line avoids both problems, because it binds the function
+  directly instead of relying on a scan. Put it after any framework or plugin
+  setup. If completion still does nothing, delete ~/.zcompdump* and start a
+  new shell.
+
+  Check the result with: print $_comps[uploads] — it prints _uploads when the
+  completion is active, and nothing when it is not.
+
+After you upgrade the CLI, generate the script again so it lists new commands.
 `;
 function bashScript() {
     const cmds = ROOT_COMMANDS.map((c) => c.name).join(" ");
@@ -140,18 +161,19 @@ function zshScript() {
     }).join("\n");
     const globalArgs = GLOBAL_FLAGS.map((g) => {
         const desc = g.summary.replace(/'/g, "'\\''");
-        // Short and long flags as separate specs when needed.
-        if (g.flag === "-w")
-            return `    '(-w --workspace)'{-w,--workspace}'[${desc}]:workspace:'`;
+        // Pair each short flag with its long form, keeping the long form's cleaner
+        // summary; the short entry then contributes nothing of its own.
         if (g.flag === "--workspace")
-            return null; // paired with -w
-        if (g.flag === "-V")
-            return `    '(-V --version)'{-V,--version}'[${desc}]'`;
+            return `    '(-w --workspace)'{-w,--workspace}'[${desc}]:workspace:'`;
+        if (g.flag === "-w")
+            return null; // paired with --workspace
         if (g.flag === "--version")
+            return `    '(-V --version)'{-V,--version}'[${desc}]'`;
+        if (g.flag === "-V")
             return null;
-        if (g.flag === "-h")
-            return `    '(-h --help)'{-h,--help}'[${desc}]'`;
         if (g.flag === "--help")
+            return `    '(-h --help)'{-h,--help}'[${desc}]'`;
+        if (g.flag === "-h")
             return null;
         if (g.flag === "--api-url")
             return `    '--api-url[${desc}]:url:'`;
@@ -162,7 +184,9 @@ function zshScript() {
         return `    '${g.flag}[${desc}]'`;
     })
         .filter(Boolean)
-        .join("\n");
+        // Every spec but the last needs a line continuation — without them zsh ends
+        // the `_arguments` call after the first spec and tries to *run* the rest.
+        .join(" \\\n");
     const subCases = ROOT_COMMANDS.filter((c) => c.subcommands?.length)
         .map((c) => {
         const lines = c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.41.0",
+  "version": "0.41.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,