@bobfrankston/npmglobalize 1.0.221 → 1.0.222

package/README.md

@@ -304,7 +304,7 @@ Notes:
 - **Git/GitHub only.** npm publish does not consume git commit messages; `npmchanges.md` lives in the git repo and on GitHub but is excluded from the published npm tarball (the standard `*.md` rule keeps only `README.md`).
 - If both `-m` and `.commitmsg` are present, `-m` wins and `.commitmsg` is left alone (not consumed).
 - If publish fails, `.commitmsg` is preserved for the next attempt.
-- Under `-local` (no publish) the file is still consumed — appended as `## v<version> (local) — <date>` and deleted, with no git commit. See [Local Install](#local-install--local).
+- Under `-local-install` (no publish) the file is still consumed — appended as `## v<version> (local) — <date>` and deleted, with no git commit. See [Local Install](#local-install--local-install).
 - `.commitmsg` is auto-added to `.npmignore` (security pattern) so it never leaks into the tarball.
 
 ### 🔧 Git Integration & Error Recovery
@@ -467,9 +467,11 @@ not what you meant to publish, so npmglobalize lists the conflicted files and st
 ```
 -install, -i    Install globally after publish (from registry)
 -link           Install globally via symlink (npm install -g .)
--local          Local install only — skip transform/publish, just npm install -g .
-                (persisted; a .commitmsg is still logged to npmchanges.md as "(local)")
--global         Clear a persisted -local in .globalize.json5 — back to the normal
+-local-install  Install from the local directory only — skip transform/publish, just
+                npm install -g . with file: deps as-is (also -localinstall; -local is
+                the deprecated old spelling). Persisted; a .commitmsg is still logged
+                to npmchanges.md as "(local)"
+-global         Clear a persisted -local-install in .globalize.json5 — back to the normal
                 transform/publish flow (publishes to npm again)
 -wsl            Also install in WSL
 -once           Don't persist flags to .globalize.json5
@@ -772,6 +774,10 @@ Cycle-safe via a shared visited set; each project is built at most once per run.
 
 This complements the existing publish cascade (which ensures version refs are correct) by closing the build-freshness gap that `npm install` alone left open.
 
+#### `bin` shebang
+
+Every file named in `package.json` `bin` must start with `#!/usr/bin/env node`. npm's Windows `.cmd` shim doesn't care, but the symlink npm creates on Linux, WSL and macOS execs the file directly, and without the shebang `sh` tries to run it and fails with a syntax error. Before each project is built, `npmglobalize` checks each `bin` file and adds the line if it is missing — in the `.ts` source when there is one (tsc carries it through to the emitted `.js`, and the touched source makes the freshness check rebuild), otherwise in the `.js` itself. A leading BOM, which would also defeat the shebang, is removed at the same time. A `bin` entry whose file does not exist yet is reported as a warning.
+
 #### Import maps (`importgen`) as a build step
 
 Browser projects that use [`importgen`](https://www.npmjs.com/package/@bobfrankston/importgen) have historically regenerated their import map from `.vscode/tasks.json`, which only runs when VS Code opens the folder — so a command-line or CI build could publish a stale map. `npmglobalize` treats the import map as a build product and moves the step into the package's own `build` script, where every build path picks it up.
@@ -838,7 +844,7 @@ Both `-flag` and `--flag` are accepted. Single-dash is the primary convention:
 ```bash
 npmglobalize -patch      # same as --patch
 npmglobalize -np         # same as --nopublish
-npmglobalize -local      # same as --local
+npmglobalize -local-install  # same as --local-install
 ```
 
 ### Persistent vs One-Shot Flags
@@ -846,7 +852,7 @@ npmglobalize -local      # same as --local
 Some flags are **persisted** to `.globalize.json5` when set from the CLI:
 - `-install`, `-link`, `-wsl`, `-files`, `-fix` — install/build preferences
 - `-np` (noPublish) — once set, prevents accidental publishes
-- `-local` — remembers "this project is local-only" (clear with `-global`)
+- `-local-install` — remembers "this project is local-only" (clear with `-global`)
 - `-git`/`-npm` visibility
 
 Other flags are **one-shot** (never persisted):
@@ -859,14 +865,14 @@ Use `-once` to prevent any flag from persisting on that run:
 npmglobalize -np -once   # No-publish this run only, don't remember it
 ```
 
-### Local Install (`-local`)
+### Local Install (`-local-install`)
 
 Skip all transform/publish logic and just run `npm install -g .` with `file:` deps as-is. Use this when you want to install a CLI tool locally for your own use without publishing anything:
 
 ```bash
-npmglobalize -local          # Install globally from local directory
-npmglobalize -local -wsl     # Also install in WSL
-npmglobalize -global         # Back to the normal transform/publish flow (publishes to npm)
+npmglobalize -local-install        # Install globally from the local directory
+npmglobalize -local-install -wsl   # Also install in WSL
+npmglobalize -global               # Back to the normal transform/publish flow (publishes to npm)
 ```
 
 This is useful for:
@@ -874,7 +880,11 @@ This is useful for:
 - Testing a CLI before publishing
 - Projects with `file:` deps that should stay as-is
 
-`-local` is persisted to `.globalize.json5` (`"local": true`), so a bare
+`-localinstall` is accepted as well. The old spelling `-local` still works but prints a
+deprecation note; it was renamed (2026-09-07) because "local" read as "local mode" rather
+than "install from the local directory".
+
+`-local-install` is persisted to `.globalize.json5` (`"local": true`), so a bare
 `npmglobalize` keeps doing local installs until you run `-global` (or edit the
 file). Nothing is committed, bumped, or published, but a `.commitmsg` is still
 consumed: it is appended to `npmchanges.md` under a
@@ -921,7 +931,7 @@ npmglobalize -install -wsl
 npmglobalize -link -wsl
 
 # Install locally without publishing (file: deps stay as-is)
-npmglobalize -local
+npmglobalize -local-install
 
 # Restore original file: references
 npmglobalize -cleanup

package/cli.js

@@ -70,9 +70,11 @@ Dependency Options:
 Install Options:
   -install, -i   Global install after publish (from registry)
   -link          Global install via symlink (npm install -g .)
-  -local         Local install only — skip transform/publish, just npm install -g .
-                 (persisted; a .commitmsg is still logged to npmchanges.md as "(local)")
-  -global        Clear a persisted -local in .globalize.json5 — back to the normal
+  -local-install Install from the local directory only — skip transform/publish, just
+                 npm install -g . with file: deps as-is (also -localinstall; -local is
+                 the deprecated old spelling). Persisted; a .commitmsg is still logged
+                 to npmchanges.md as "(local)"
+  -global        Clear a persisted -local-install in .globalize.json5 — back to the normal
                  transform/publish flow (publishes to npm again)
   -wsl           Also install globally in WSL
   -freeze        Freeze node_modules (replace symlinks with real copies for network shares)
@@ -157,8 +159,8 @@ Examples:
   npmglobalize -fix                  Fix security vulnerabilities
   npmglobalize -install -wsl         Release + install on Windows and WSL (from registry)
   npmglobalize -link -wsl            Release + link on Windows and WSL (symlink)
-  npmglobalize -local                Install locally with file: deps as-is (no publish)
-  npmglobalize -local -wsl           Local install on Windows and WSL
+  npmglobalize -local-install        Install from the local directory, file: deps as-is (no publish)
+  npmglobalize -local-install -wsl   Local install on Windows and WSL
   npmglobalize -global               Leave local-only mode; publish to npm from now on
   npmglobalize -np                   Just transform, no publish (remembered in config)
   npmglobalize -cleanup              Restore original dependencies
@@ -228,11 +230,21 @@ function parseArgs(args) {
             case '-cleanup':
                 options.cleanup = true;
                 break;
+            // 2026-09-07 — Claude Code (Fable 5.1), at Bob's direction: "-local is
+            // confusing" — it read like "local mode" / "local deps" rather than "install
+            // from the local directory". Renamed to -local-install (-localinstall also
+            // accepted). -local still works but says so, so muscle memory isn't broken
+            // and the old spelling is phased out rather than silently kept alive.
+            // The .globalize.json5 key stays "local" so existing configs keep working.
             case '-local':
+                console.log(colors.yellow('!  -local is deprecated — use -local-install (same meaning: npm install -g . from the local directory, no publish)'));
+            // falls through
+            case '-local-install':
+            case '-localinstall':
                 options.local = true;
                 options.explicitKeys.add('local');
                 break;
-            // 2026-09-01 16:30 EDT — Claude Code (Opus 5), at Bob's direction. -local
+            // 2026-09-01 16:30 EDT — Claude Code (Opus 5), at Bob's direction. -local-install
             // persists to .globalize.json5 but had no counterpart, so leaving local-only
             // mode meant hand-editing the config. Same shape as -publish for -np.
             // 2026-09-01 15:00 EDT — Bob: "-global makes more sense, -nolocal is confusing";

package/lib.d.ts

@@ -456,6 +456,8 @@ export declare function ensureBuildScript(cwd: string): Promise<{
  *  was skipped because there was nothing to build / the user declined the
  *  build-script prompt / output already up to date). Pass `forceBuild` to
  *  skip the freshness check. */
+/** Every `bin` entry gets a `#!/usr/bin/env node` first line, added to the source if missing. */
+export declare function ensureBinShebang(cwd: string): void;
 export declare function buildProject(cwd: string, opts?: {
     verbose?: boolean;
     force?: boolean;

package/lib.js

@@ -332,7 +332,7 @@ const BOOL_COMMENTS = {
     quiet: { on: 'Suppress npm warnings', off: 'Show npm warnings' },
     verbose: { on: 'Show detailed output', off: 'Normal output detail' },
     fix: { on: 'Auto-run npm audit fix (default)', off: 'Do NOT run npm audit fix (audit report still runs)' },
-    local: { on: 'Local install only (skip transform/publish)', off: 'Normal transform/publish flow' },
+    local: { on: 'Local install only via -local-install (skip transform/publish)', off: 'Normal transform/publish flow' },
     noPublish: { on: 'Transform but don\'t publish', off: 'Publish normally' },
     freeze: { on: 'Freeze node_modules (replace symlinks with real copies)', off: 'Leave node_modules symlinks as-is' },
     usePaths: { on: 'Resolve file: deps from sibling checkouts', off: 'Resolve file: deps from npm, not siblings (standalone package)' },
@@ -444,7 +444,7 @@ export function writeConfig(dir, config, explicitKeys) {
         ['"gitVisibility": "private"', 'Git repo: private or public'],
         ['"npmVisibility": "private"', 'npm package: private or public'],
         ['"fix": true', 'true = auto-run npm audit fix (never --force); false = report only'],
-        ['"local": false', 'true = local install only (skip transform/publish); clear with -global'],
+        ['"local": false', 'true = install from the local directory only, set by -local-install (skip transform/publish); clear with -global'],
         ['"noPublish": false', 'true = transform but don\'t publish'],
         ['"freeze": false', 'true = freeze node_modules (replace symlinks with real copies)'],
         ['"usePaths": true', 'true = resolve file: deps from siblings; false = use latest npm version (standalone)'],
@@ -3536,7 +3536,48 @@ export async function ensureBuildScript(cwd) {
  *  was skipped because there was nothing to build / the user declined the
  *  build-script prompt / output already up to date). Pass `forceBuild` to
  *  skip the freshness check. */
+// 2026-09-07 — Claude Code (Fable 5.1), at Bob's direction: "When a program is
+// installed, at least locally, it needs a shebang for node. Make sure the main
+// program has a shebang." npm's Windows .cmd shim doesn't care, but the symlink
+// npm creates on Linux/WSL/macOS execs the file directly, so a bin entry
+// without `#!/usr/bin/env node` fails there with "syntax error" from sh. The
+// shebang belongs in the SOURCE (.ts): tsc carries it through to the emitted
+// .js, and editing the .ts bumps its mtime so the freshness check rebuilds.
+// Runs ahead of the build for that reason, and for every package in the
+// cascade, since a file: dep can be a CLI too.
+/** Every `bin` entry gets a `#!/usr/bin/env node` first line, added to the source if missing. */
+export function ensureBinShebang(cwd) {
+    let pkg;
+    try {
+        pkg = readPackageJson(cwd);
+    }
+    catch {
+        return;
+    } // no package.json: nothing to check, the build reports that
+    if (!pkg?.bin)
+        return;
+    const targets = typeof pkg.bin === 'string' ? [pkg.bin]
+        : (typeof pkg.bin === 'object' ? Object.values(pkg.bin).filter((v) => typeof v === 'string') : []);
+    for (const rel of targets) {
+        const emitted = path.join(cwd, rel);
+        // Prefer the TypeScript source the bin file is emitted from.
+        const tsSibling = emitted.replace(/\.(m|c)?js$/i, '.$1ts');
+        const file = tsSibling !== emitted && fs.existsSync(tsSibling) ? tsSibling : emitted;
+        if (!fs.existsSync(file)) {
+            console.log(colors.yellow(`!  bin "${rel}" in ${pkg.name}: file not found (needs a #!/usr/bin/env node shebang once it exists)`));
+            continue;
+        }
+        const raw = fs.readFileSync(file, 'utf-8');
+        const body = raw.startsWith('') ? raw.slice(1) : raw; // a BOM ahead of #! defeats the shebang
+        if (body.startsWith('#!'))
+            continue;
+        fs.writeFileSync(file, `#!/usr/bin/env node
+${body}`, 'utf-8');
+        console.log(colors.green(`+ Added #!/usr/bin/env node to ${path.relative(cwd, file)} (bin "${rel}")`));
+    }
+}
 export async function buildProject(cwd, opts = {}) {
+    ensureBinShebang(cwd);
     // Fix removed-in-TS7 tsconfig settings up front rather than waiting for a
     // build to fail on them. A deprecated `moduleResolution` is only a *hard*
     // error under the tsc that flags it (TS6+, and the editor's bundled
@@ -6529,15 +6570,15 @@ export function getToolVersion() {
     }
 }
 // 2026-09-01 16:30 EDT — Claude Code (Opus 5), at Bob's direction.
-// Under -local the run returned before any of the .commitmsg handling, so the
+// Under -local-install the run returned before any of the .commitmsg handling, so the
 // notes a local-only package accumulated in .commitmsg were never recorded
 // anywhere — they sat in the file, and the next edit overwrote them. A local
 // install is still a change worth a history line, so the same npmchanges.md
 // gets the entry, tagged "(local)" because nothing was published or bumped
 // (several local runs may legitimately share one version number). No git
-// activity: -local is the path taken when there is often no repo at all, and
+// activity: -local-install is the path taken when there is often no repo at all, and
 // when there is one the next real publish commits npmchanges.md with the rest.
-/** Consume .commitmsg for a -local run: append to npmchanges.md, delete the file. */
+/** Consume .commitmsg for a -local-install run: append to npmchanges.md, delete the file. */
 function recordLocalChange(cwd, version, dryRun) {
     const commitMsgPath = path.join(cwd, '.commitmsg');
     if (!fs.existsSync(commitMsgPath))
@@ -6572,8 +6613,8 @@ function recordLocalChange(cwd, version, dryRun) {
         console.error(colors.yellow(`  Warning: could not update npmchanges.md: ${err.message}`));
     }
 }
-/** Perform local-only install (npm install -g .) — the single -local path, reached
- *  from the -local flag / config and from the git-init prompts' "local only" choice. */
+/** Perform local-only install (npm install -g .) — the single -local-install path, reached
+ *  from the -local-install flag / config and from the git-init prompts' "local only" choice. */
 async function doLocalInstall(cwd, options) {
     const { dryRun = false, wsl = false } = options;
     const pkg = readPackageJson(cwd);
@@ -6693,7 +6734,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         if (configOptions.show)
             settings.push('--show');
         if (configOptions.local)
-            settings.push('-local');
+            settings.push('-local-install');
         if (configOptions.freeze)
             settings.push('-freeze');
         if (configOptions.usePaths === false)
@@ -6710,8 +6751,8 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         }
     }
     console.log('');
-    // -local: skip all transform/publish, just install from local directory with file: deps intact.
-    // -local is testing-only and must NOT mutate package.json — packages are meant to be installed
+    // -local-install: skip all transform/publish, just install from local directory with file: deps intact.
+    // -local-install is testing-only and must NOT mutate package.json — packages are meant to be installed
     // as published public packages by end users; the bin field is whatever the published shape is.
     // Library members (no bin) are silently skipped: nothing for global install to expose.
     // 2026-09-01 16:30 EDT — Claude Code (Opus 5): this was a verbatim copy of
@@ -9017,7 +9058,7 @@ export async function globalizeWorkspace(rootDir, options = {}, configOptions =
     console.log(`Packages (${packages.length}): ${packages.map(p => p.name).join(', ')}`);
     console.log(`Publish order: ${publishOrder.join(' → ')}`);
     console.log('');
-    // Warn if -local / -install are present at the workspace root: those are
+    // Warn if -local-install / -install are present at the workspace root: those are
     // component-level concerns. In workspace mode they only act on members
     // that have a `bin` field; libraries are silently skipped. Telling the
     // user up front avoids the surprise of "I asked for install but most
@@ -9025,7 +9066,7 @@ export async function globalizeWorkspace(rootDir, options = {}, configOptions =
     const installSources = [];
     if (options.local || configOptions.local) {
         const src = configOptions.local && !options.local ? '.globalize.json5' : 'CLI';
-        installSources.push(`-local (${src})`);
+        installSources.push(`-local-install (${src})`);
     }
     if (options.install || configOptions.install) {
         const src = configOptions.install && !options.install ? '.globalize.json5' : 'CLI';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.221",
+  "version": "1.0.222",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@bobfrankston/freezepak": "^0.1.9",
-    "@bobfrankston/importgen": "^0.1.42",
+    "@bobfrankston/importgen": "^0.1.43",
     "@bobfrankston/themecolors": "^0.1.9",
     "@bobfrankston/userconfig": "^1.0.11",
     "@npmcli/package-json": "^7.0.4",
@@ -60,7 +60,7 @@
   ".transformedSnapshot": {
     "dependencies": {
       "@bobfrankston/freezepak": "^0.1.9",
-      "@bobfrankston/importgen": "^0.1.42",
+      "@bobfrankston/importgen": "^0.1.43",
       "@bobfrankston/themecolors": "^0.1.9",
       "@bobfrankston/userconfig": "^1.0.11",
       "@npmcli/package-json": "^7.0.4",