Release artifacts for nu-hooks / custom-completions in a monorepo

[tonythethompson]

nu_scripts is a different beast from the single-module repos we've been onboarding — wanted to ask how you think about release artifacts before we assume the wrong model.

Context: Numan (package manager, hash-verified installs) now lists two slices of this repo, both pinned at f04cb44:

Registry name	What we packaged
nushell/nu-hooks@0.1.0	the nu-hooks/ tree
nushell/custom-completions@0.1.0-f04cb44	custom-completions/

nupm already consumes this repo via git revision pins, which fits a monorepo. Numan wants a downloadable artifact per entry, so we built mirrors on our side rather than using /archive/{commit}.zip (same byte-stability concerns as tag archives).

What I'm trying to learn:

1. nu-hooks — hooks are individual .nu files under subdirs, no top-level mod.nu. Is a subfolder zip on releases something you'd ever want, or should git pins remain the canonical distribution?

2. custom-completions — big, churny tree. Periodic snapshot releases? Split repo? Or "registry mirrors forever" is expected for this kind of content?

Not looking for a drive-by Actions PR — this repo's release story is yours. Mostly want to know if we're fighting the grain by mirroring, or if there's a lightweight convention you'd prefer (even if it's "please keep mirroring").

For reference, a single-module upstream recently added an uploaded zip after a similar conversation: nutest#29 → v1.2.0 asset.

[fdncred]

This repo is mostly community driven. I try to keep things a little reasonable but there's a lot of organization missing here. I'd be open to hearing proposals about how to make this repo more package manager friendly. I'm not really worried about moving things around as long as there's a logical structure that people can come to rely on.

[tonythethompson]

Thanks for being open to this. I'll follow up here with a short concrete proposal covering:

1. nu-hooks - versioned zip layout (tagged subfolder snapshots vs. a dedicated release path)
2. custom-completions - snapshot cadence for commit-pinned installs
3. Numan constraints - byte-stable release archives (.zip\ / .tar.gz), not GitHub /archive/\ zipballs

Goal is something maintainers can rely on without heavy process overhead.

[fdncred]

Sounds like a lot of CI work. I'm personally not up for maintaining a lot of CI mess because I find it fiddly. However, I'm open to allowing others to maintain nu_scripts and it's releases.

[tonythethompson]

Concrete proposal (happy to revise):

Goal

Let nupm git pins stay canonical for this monorepo while giving hash-pinned consumers (Numan, others) uploaded release assets they can rely on. We do not need a repo restructure unless you want one for other reasons.

What Numan needs

• Uploaded GitHub Release assets (.zip or .tar.gz)
• Byte-stable per version id (re-upload only if a tag moves)
• Not GitHub /archive/{ref}.zip auto-zipballs (those are not promised stable)

nu-hooks (install-only today)

Hooks are independent subdirs under nu-hooks/, no top-level mod.nu. That is fine.

Proposal: optional subfolder asset on releases:

nu-hooks-{id}.zip
└── nu-hooks-{id}/
    └── hooks/...          # same tree as repo nu-hooks/

• {id} = short commit (f04cb44) or a dated snapshot label (2026-07-06) if you prefer not to semver the monorepo.
• Numan already lists this as install-only (per-hook activation is manual). A zip is for reproducible fetch, not a new activation model.

Alternative: declare git pins the only supported path for hooks; Numan keeps mirroring. Low cost either way on your side.

custom-completions (high churn)

85+ completion trees; content changes often.

Proposal (pick one):

1. Registry mirrors long-term (default assumption). nupm/git remains canonical; we rebuild mirrors when we bump pins. No upstream release burden.
2. Periodic snapshot releases (e.g. monthly or when someone asks): custom-completions-{id}.zip with the same subfolder layout. Good if you want a stable artifact cadence without splitting the repo.
3. Split repo only if you want completions maintained separately for non-package-manager reasons. Probably overkill just for Numan.

Suggested lightweight convention

If you want any upstream artifacts without heavy process:

• One GitHub Release per snapshot (tag name your choice: date, commit, or packages-*).
• Attach 0–2 zips (nu-hooks-…, custom-completions-…) built with git archive on the relevant subpaths.
• Document in README that nupm git revision pins are still primary; zips are for download-based package managers.

We can keep mirroring indefinitely if none of this is worth maintaining. Mostly looking for a convention people can rely on.

Reference: single-module precedent nutest v1.2.0 after nutest#29.

[tonythethompson]

Re: CI — totally fair. We don't need you to maintain any of that.

Registry mirrors on our side are the default for nu-hooks and custom-completions; nupm git pins stay canonical. If the community ever wants uploaded snapshot zips, that can be a volunteer-owned workflow/PR, not something on your plate.

Happy to keep mirroring indefinitely.

[fdncred]

I really don't see storing zips or tar.gz files as a good idea for this repo. This repo is already too big with all the screenshots in it and adding multiple generations of zip and tar.gz just seems untenable.

However, I'm up for better organization of folders to make finding what you're looking for easier and/or to make a package manager's life easier.

[tonythethompson]

Follow-up on the earlier packing discussion (no zip hosting; agreed).

You mentioned openness to folder organization that makes package managers' lives easier. That's the angle I'd actually use next.

What I'm doing short-term

Keeping registry-hosted mirrors for:

• nushell/nu-hooks
• nushell/custom-completions (whole tree)
• nushell/git-completions (git slice; already split out for search)

Next wave likely adds more per-tool completion packages (cargo / npm / make / winget / …) as separate Numan entries, still mirrored from this repo at a pinned commit. No request that you store zip/tar artifacts here.

Lightweight organization ask (optional)

If you ever reorganize, these conventions would reduce special-casing on my side (and probably help nupm/git consumers too):

1. Keep one directory per completion tool under custom-completions/<tool>/ with a single obvious entry *-completions.nu (already mostly true).
2. Prefer stable directory names over renames when possible (registry ids and docs link paths).
3. For anything meant as a standalone module (weather, extractors, etc.), a clear mod.nu (or documented entry) at the slice root helps activation tools.

No CI, no release assets, no size growth. If you'd rather leave structure alone, mirrors stay fine. This is not a blocker, just a standing preference if reorganization energy appears.

Happy to draft a small README section under custom-completions/ describing "how package managers should pin slices" if that would help contributors.

[fdncred]

My preference for organization for a while now has been:

1. folder name for tool, module
2. readme.md telling what this is and where to get it
3. completions / module nu file

I realize everything isn't like that but it would be great if everything were and when people submit things I try to remind them of this pattern.

I'm open to a readme for custom completions for package managers.

[tonythethompson]

That pattern matches what packagers need. Thanks for confirming.

Here's what I have in mind for a short addition to custom-completions/README.md. I'm happy to open a PR with this or a revised version, or I can leave it to you for now.

---

For packagers

Preferred layout per tool:

custom-completions/<tool>/
  readme.md
  <tool>-completions.nu

Pin a git revision and path into that folder (or the whole tree). Prefer stable directory names; renames break links and package ids. This repo does not host release zip/tar assets for these trees.

---

[fdncred]

good enough