# npmglobalize — `--dist-tag` flag plumbing

Purpose: let callers pass `--tag <name>` through to `npm publish` so a release can land on a non-`latest` dist-tag without modifying `package.json`. Required by `mailx`'s prod/dev workflow (`docs/prod.md`); benign for every other consumer (default behavior unchanged).

## File

`/c/users/bob/onedrive/xfer/bin/linuxbin/node_modules/@bobfrankston/npmglobalize/lib.js`

(Or wherever the maintained source lives — this file is the deployed copy. Edit the source repo instead and rebuild if there's one.)

## Step 1 — argv parsing

Near the top of the script where other CLI flags are read, accept `--dist-tag` (and an alias `--tag`) followed by a tag name. Skip the value for the rest of argv processing.

```js
let distTag = "";
{
    const idx = process.argv.findIndex(a => a === "--dist-tag" || a === "--tag");
    if (idx !== -1) {
        distTag = process.argv[idx + 1] || "";
        if (!distTag || distTag.startsWith("-")) {
            console.error("npmglobalize: --dist-tag requires a tag name");
            process.exit(1);
        }
        process.argv.splice(idx, 2);
    }
}
```

If npmglobalize already centralizes argv parsing (e.g. via minimist or a custom routine), insert the same logic in that path instead. Either way: extract once, store in a module-scope variable, strip from argv so downstream code doesn't see it.

## Step 2 — forward to `npm publish`

Around line 4486:

```js
const npmArgs = ['publish', tarballName];
```

Change to:

```js
const npmArgs = ['publish', tarballName];
if (distTag) npmArgs.push('--tag', distTag);
```

That's the entire publish-side change. When `distTag` is empty (the default), `npmArgs` is identical to before.

## Step 3 — log line

Where the script announces "Publishing X@Y to npm…", include the tag if present:

```js
console.log(`Publishing ${name}@${version} to npm${distTag ? ` (tag ${distTag})` : ""}…`);
```

Helps the rebuild-cmd output show clearly that the publish landed on `dev` and not `latest`.

## Step 4 — verify

```bash
# In a workspace whose package.json is publishable:
npmglobalize --dist-tag dev
npm view @bobfrankston/<package> dist-tags
# Expect: { latest: '<previous>', dev: '<just-published>' }
```

Run again without the flag:

```bash
npmglobalize
npm view @bobfrankston/<package> dist-tags
# Expect: { latest: '<just-published>', dev: '<earlier>' }
```

If the second run accidentally bumped `dev` instead of `latest`, the argv strip in Step 1 didn't run.

## Step 5 — release npmglobalize itself

If npmglobalize is installed via npm (it is — `@bobfrankston/npmglobalize`), bump its own version, publish, then `npm install -g @bobfrankston/npmglobalize` on every machine that uses it. Otherwise the new flag is only present on the machine you edited.

## What this does NOT change

- Default publish target stays `@latest` — every existing caller of `npmglobalize` keeps working.
- No effect on version bumping, git-tag pushing, build orchestration, or the `package.json` `dependencies` rewrite. The flag only adds to the final `npm publish` invocation.
- Does not replace existing scripts that read npm dist-tags. dist-tags are managed in two ways now: (a) at publish time via `--tag`, (b) post-publish via `npm dist-tag add/rm`. Step 2 above only adds (a).

## Effort estimate

5 lines of code + a log-line tweak + a publish of npmglobalize. Maybe 15 minutes wall-clock including the verification steps.
