@bobfrankston/npmglobalize 1.0.154 → 1.0.155

package/README.md

@@ -301,6 +301,8 @@ Publishing requires being on a branch so commits and tags can be properly tracke
 -force-publish           Republish dependencies even if version exists
 -fix                     Run npm audit fix after transformation
 -no-fix                  Don't run npm audit
+-no-use-paths, -nup      Declare package standalone; do not resolve file: deps
+                         from sibling checkouts (see Configuration File)
 ```
 
 ### Install Options
@@ -323,10 +325,21 @@ Publishing requires being on a branch so commits and tags can be properly tracke
 -git private    Set GitHub repo to private (default for new repos)
 -git public     Set GitHub repo to public (requires confirmation)
                 Works on both new and existing repos
--npm private    Mark npm package private (skip publish) (default)
--npm public     Publish to npm
+-npm <values>   Comma-separated list of npm options:
+                  private (default) | public — package visibility
+                  ts                         — keep .ts source (and *.map,
+                                               tsconfig.json) in npm tarball
+                  nts                        — exclude .ts source
+                                               (default for non-noEmit projects)
+                Example: -npm public,ts
 ```
 
+`ts` is already the default on git (source is tracked). Pass `-npm ts` to ship
+the same files to npm — useful for debugging installed packages or "source on
+demand" packages. `noEmit` projects automatically ship `.ts` files (they *are*
+the runtime); pass `-npm nts` to override. `allowTs` persists to
+`.globalize.json5`.
+
 ### Workspace Options
 ```
 -w, -workspace <pkg>   Filter to specific package (repeatable)
@@ -400,12 +413,26 @@ Settings can be saved in `.globalize.json5`:
   "fix": true,               // Auto-run npm audit fix
   "verbose": false,          // Show detailed output
   "gitVisibility": "private",
-  "npmVisibility": "public"
+  "npmVisibility": "public",
+  "usePaths": true           // Resolve file: deps from sibling checkouts (see below)
 }
 ```
 
 Configuration persists across runs. CLI flags override config file.
 
+### `usePaths` — Standalone packages
+
+Default: `true`. Set to `false` (or pass `-no-use-paths` / `-nup`) to mark a
+package as **standalone** — one that should be publishable/installable on a
+machine that does not have sibling `file:` dep checkouts available. Example:
+a backup/recovery utility you want to `npm install -g` on any host.
+
+Currently this setting is **declarative** — it is parsed, persisted to
+`.globalize.json5`, and surfaced in the settings banner, but the tool does
+not yet change its behavior based on it. Behavior wiring (e.g. resolving
+`file:` deps to the latest published npm version instead of walking siblings)
+is planned.
+
 ## Common Workflows
 
 ### Standard Release

package/cli.js

@@ -37,6 +37,9 @@ Dependency Options:
   -no-prescan, -nps        Skip upfront dep-graph prescan
   -force-publish           Republish dependencies even if version exists
   -fix                     Run npm audit fix after transformation
+  -no-use-paths, -nup      Declare this package standalone — file: deps shouldn't
+                           be resolved from sibling checkouts (persisted as
+                           usePaths:false in .globalize.json5; FYI for now)
 
 Install Options:
   -install, -i   Global install after publish (from registry)
@@ -57,8 +60,12 @@ Git/npm Visibility:
   -git private    Set GitHub repo to private (default for new repos)
   -git public     Set GitHub repo to public (requires confirmation)
                   Works on both new and existing repos
-  -npm private    Mark npm package private (skip publish) (default)
-  -npm public     Publish to npm
+  -npm <values>   Comma-separated list of npm options:
+                    private (default) | public — package visibility
+                    ts                         — keep .ts source in npm tarball
+                    nts                        — exclude .ts source (default for
+                                                 non-noEmit projects)
+                  Example: -npm public,ts
 
 Workspace Options:
   -w, -workspace <pkg>  Filter to specific package (repeatable)
@@ -214,12 +221,30 @@ function parseArgs(args) {
                 break;
             case '-npm':
                 i++;
-                if (args[i] === 'private' || args[i] === 'public') {
-                    options.npmVisibility = args[i];
-                    options.explicitKeys.add('npmVisibility');
+                if (!args[i]) {
+                    options.error = `-npm requires a value (private|public, ts, nts — comma-separated)`;
+                    break;
                 }
-                else {
-                    options.error = `-npm requires 'private' or 'public', got: ${args[i]}`;
+                {
+                    const tokens = args[i].split(',').map(t => t.trim()).filter(t => t);
+                    for (const tok of tokens) {
+                        if (tok === 'private' || tok === 'public') {
+                            options.npmVisibility = tok;
+                            options.explicitKeys.add('npmVisibility');
+                        }
+                        else if (tok === 'ts') {
+                            options.allowTs = true;
+                            options.explicitKeys.add('allowTs');
+                        }
+                        else if (tok === 'nts') {
+                            options.allowTs = false;
+                            options.explicitKeys.add('allowTs');
+                        }
+                        else {
+                            options.error = `-npm: unknown value '${tok}' (expected private|public|ts|nts)`;
+                            break;
+                        }
+                    }
                 }
                 break;
             case '-message':
@@ -266,6 +291,11 @@ function parseArgs(args) {
             case '-npd':
                 options.publishDeps = false; // Disable auto-publishing
                 break;
+            case '-no-use-paths':
+            case '-nup':
+                options.usePaths = false; // Skip sibling-path resolution; use latest npm version for file: deps
+                options.explicitKeys.add('usePaths');
+                break;
             case '-no-prescan':
             case '-nps':
                 options.noPrescan = true;

package/lib/config.js

@@ -58,7 +58,8 @@ export function writeConfig(dir, config, explicitKeys) {
         wsl: false,
         force: false,
         verbose: false,
-        freeze: false
+        freeze: false,
+        usePaths: true
     };
     // Read existing config to preserve values
     const existing = readConfig(dir);
@@ -119,6 +120,8 @@ export function writeConfig(dir, config, explicitKeys) {
                 comment = '  // Transform but don\'t publish';
             else if (key === 'freeze')
                 comment = '  // Freeze node_modules (replace symlinks with real copies)';
+            else if (key === 'usePaths')
+                comment = '  // Resolve file: deps from sibling checkouts (set false for standalone packages)';
             lines.push(`  "${key}": ${jsonValue}${comma}${comment}`);
         });
         lines.push('');
@@ -139,6 +142,7 @@ export function writeConfig(dir, config, explicitKeys) {
     lines.push('  // "local": false              // Local install only (skip transform/publish)');
     lines.push('  // "noPublish": false          // Transform but don\'t publish');
     lines.push('  // "freeze": false              // Freeze node_modules (replace symlinks with real copies)');
+    lines.push('  // "usePaths": true              // Resolve file: deps from siblings; false = use latest npm version (standalone)');
     lines.push('}');
     fs.writeFileSync(configPath, lines.join('\n') + '\n');
 }

package/lib/types.d.ts

@@ -78,6 +78,11 @@ export interface GlobalizeOptions {
     once?: boolean;
     /** Run importgen to update import maps before publishing */
     importgen?: boolean;
+    /** Use filesystem paths for `file:` deps (default true). Set false to
+     *  mark a package as publishable/installable even when sibling checkouts
+     *  are absent. Currently declarative (recorded in config and displayed);
+     *  the actual conversion path is TODO. */
+    usePaths?: boolean;
     /** Local install only — skip transform/publish, just npm install -g . */
     local?: boolean;
     /** Freeze node_modules: replace symlinks/junctions with real copies for network share use */

package/lib.d.ts

@@ -55,6 +55,10 @@ export interface GlobalizeOptions {
     gitVisibility?: 'private' | 'public';
     /** npm visibility: private (default) or public */
     npmVisibility?: 'private' | 'public';
+    /** Allow .ts source files (and *.map, tsconfig.json) in the published npm tarball.
+     *  undefined: follow noEmit detection (noEmit → allow). true: always allow.
+     *  false: always exclude via .npmignore. Set via `-npm ts` / `-npm nts`. */
+    allowTs?: boolean;
     /** Custom commit message */
     message?: string;
     /** Check and update ignore files to conform to best practices */
@@ -91,6 +95,11 @@ export interface GlobalizeOptions {
     once?: boolean;
     /** Run importgen to update import maps before publishing */
     importgen?: boolean;
+    /** Use filesystem paths for `file:` deps (default true). Set false to
+     *  mark a package as publishable/installable even when sibling checkouts
+     *  are absent. Currently declarative (recorded in config and displayed);
+     *  the actual conversion path is TODO. */
+    usePaths?: boolean;
     /** Local install only — skip transform/publish, just npm install -g . */
     local?: boolean;
     /** Freeze node_modules: replace symlinks/junctions with real copies for network share use */
@@ -278,7 +287,7 @@ export declare function promptText(message: string, defaultValue?: string): Prom
 /** Prompt user for multiple choice */
 export declare function promptChoice(message: string, choices: string[]): Promise<string | null>;
 /** Initialize git repository */
-export declare function initGit(cwd: string, visibility: 'private' | 'public', dryRun: boolean): Promise<boolean>;
+export declare function initGit(cwd: string, visibility: 'private' | 'public', dryRun: boolean, allowTs?: boolean): Promise<boolean>;
 /** Main globalize function */
 /** Run npm audit and optionally fix vulnerabilities */
 export declare function runNpmAudit(cwd: string, fix?: boolean, verbose?: boolean): {

package/lib.js

@@ -230,7 +230,8 @@ export function writeConfig(dir, config, explicitKeys) {
         wsl: false,
         force: false,
         verbose: false,
-        freeze: false
+        freeze: false,
+        usePaths: true
     };
     // Read existing config to preserve values
     const existing = readConfig(dir);
@@ -291,6 +292,10 @@ export function writeConfig(dir, config, explicitKeys) {
                 comment = '  // Transform but don\'t publish';
             else if (key === 'freeze')
                 comment = '  // Freeze node_modules (replace symlinks with real copies)';
+            else if (key === 'usePaths')
+                comment = '  // Resolve file: deps from sibling checkouts (set false for standalone packages)';
+            else if (key === 'allowTs')
+                comment = '  // Keep .ts source (and *.map, tsconfig.json) in the published npm tarball';
             lines.push(`  "${key}": ${jsonValue}${comma}${comment}`);
         });
         lines.push('');
@@ -311,6 +316,8 @@ export function writeConfig(dir, config, explicitKeys) {
     lines.push('  // "local": false              // Local install only (skip transform/publish)');
     lines.push('  // "noPublish": false          // Transform but don\'t publish');
     lines.push('  // "freeze": false              // Freeze node_modules (replace symlinks with real copies)');
+    lines.push('  // "usePaths": true              // Resolve file: deps from siblings; false = use latest npm version (standalone)');
+    lines.push('  // "allowTs": false              // Include .ts source in npm tarball (auto-true for noEmit projects)');
     lines.push('}');
     fs.writeFileSync(configPath, lines.join('\n') + '\n');
 }
@@ -1858,9 +1865,16 @@ function isNoEmitProject(cwd) {
         return false;
     }
 }
-/** Get applicable npmignore patterns, excluding TS patterns for noEmit projects */
-function getApplicableNpmignorePatterns(cwd) {
-    if (isNoEmitProject(cwd)) {
+/** Resolve whether .ts source files should be kept in the published tarball.
+ *  Explicit allowTs wins; otherwise noEmit projects default to including .ts. */
+function resolveAllowTs(cwd, allowTs) {
+    if (allowTs !== undefined)
+        return allowTs;
+    return isNoEmitProject(cwd);
+}
+/** Get applicable npmignore patterns, excluding TS patterns when .ts files should ship */
+function getApplicableNpmignorePatterns(cwd, allowTs) {
+    if (resolveAllowTs(cwd, allowTs)) {
         return ALL_NPMIGNORE.filter(p => !TS_NPMIGNORE_PATTERNS.has(p));
     }
     return ALL_NPMIGNORE;
@@ -2223,7 +2237,7 @@ function checkIgnoreFiles(cwd, options) {
     if (fs.existsSync(npmignorePath)) {
         const content = fs.readFileSync(npmignorePath, 'utf-8');
         const lines = content.split('\n').map(l => l.trim());
-        const applicableNpm = getApplicableNpmignorePatterns(cwd);
+        const applicableNpm = getApplicableNpmignorePatterns(cwd, options.allowTs);
         for (const pattern of applicableNpm) {
             if (!lineHasPattern(lines, pattern)) {
                 if (securityNpm.has(pattern)) {
@@ -2234,13 +2248,21 @@ function checkIgnoreFiles(cwd, options) {
                 }
             }
         }
+        // If .ts should ship, flag TS patterns already in .npmignore for removal
+        if (resolveAllowTs(cwd, options.allowTs)) {
+            for (const ts of TS_NPMIGNORE_PATTERNS) {
+                if (lineHasPattern(lines, ts)) {
+                    changes.push(`  .npmignore has (should remove): ${ts}`);
+                }
+            }
+        }
     }
     const needsUpdate = changes.length > 0 || securityChanges.length > 0;
     return { needsUpdate, changes, securityChanges };
 }
 /** Update ignore files to conform to best practices.
  *  securityOnly: if true, only add security patterns (auto-fix without prompting). */
-function conformIgnoreFiles(cwd, securityOnly = false) {
+function conformIgnoreFiles(cwd, securityOnly = false, allowTs) {
     if (!securityOnly) {
         // Ensure .gitattributes for LF line endings (use proper helper)
         ensureGitattributes(cwd);
@@ -2259,8 +2281,8 @@ function conformIgnoreFiles(cwd, securityOnly = false) {
         }
     }
     const patternsGit = securityOnly ? getSecurityGitignorePatterns() : getApplicableGitignorePatterns(cwd);
-    const patternsNpm = securityOnly ? getSecurityNpmignorePatterns() : getApplicableNpmignorePatterns(cwd);
-    const noEmit = isNoEmitProject(cwd);
+    const patternsNpm = securityOnly ? getSecurityNpmignorePatterns() : getApplicableNpmignorePatterns(cwd, allowTs);
+    const shipTs = resolveAllowTs(cwd, allowTs);
     // Update .gitignore
     const gitignorePath = path.join(cwd, '.gitignore');
     if (fs.existsSync(gitignorePath)) {
@@ -2287,8 +2309,8 @@ function conformIgnoreFiles(cwd, securityOnly = false) {
         const lines = content.split('\n').map(l => l.trim());
         const newLines = new Set(lines.filter(l => l));
         let updated = false;
-        if (!securityOnly && !noEmit) {
-            // Add TypeScript exclusions (only in full conform, skip for noEmit projects)
+        if (!securityOnly && !shipTs) {
+            // Add TypeScript exclusions (only in full conform, skip when .ts should ship)
             for (const ts of ['*.ts', '!*.d.ts', '*.map']) {
                 if (!newLines.has(ts)) {
                     newLines.add(ts);
@@ -2296,8 +2318,8 @@ function conformIgnoreFiles(cwd, securityOnly = false) {
                 }
             }
         }
-        // For noEmit projects, remove TS patterns that shouldn't be ignored
-        if (noEmit) {
+        // When .ts should ship (noEmit or allowTs=true), remove TS patterns
+        if (shipTs) {
             for (const ts of TS_NPMIGNORE_PATTERNS) {
                 if (newLines.has(ts)) {
                     newLines.delete(ts);
@@ -2314,8 +2336,9 @@ function conformIgnoreFiles(cwd, securityOnly = false) {
         if (updated) {
             const newContent = Array.from(newLines).join('\n') + '\n';
             fs.writeFileSync(npmignorePath, newContent);
-            if (noEmit) {
-                console.log(colors.cyan('  ✓ .npmignore updated (noEmit: kept *.ts files)'));
+            if (shipTs) {
+                const reason = allowTs === true ? 'allowTs' : 'noEmit';
+                console.log(colors.cyan(`  ✓ .npmignore updated (${reason}: kept *.ts files)`));
             }
             else {
                 console.log(colors.cyan('  ✓ Auto-added security patterns to .npmignore'));
@@ -2374,11 +2397,11 @@ function ensureGitignore(cwd) {
     }
 }
 /** Ensure .npmignore exists with recommended patterns */
-function ensureNpmignore(cwd) {
+function ensureNpmignore(cwd, allowTs) {
     const npmignorePath = path.join(cwd, '.npmignore');
     if (!fs.existsSync(npmignorePath)) {
         console.log('  Creating .npmignore...');
-        const patterns = getApplicableNpmignorePatterns(cwd);
+        const patterns = getApplicableNpmignorePatterns(cwd, allowTs);
         const content = patterns.join('\n') + '\n';
         fs.writeFileSync(npmignorePath, content);
         console.log(colors.green('  ✓ .npmignore created'));
@@ -2405,7 +2428,7 @@ function ensureGitattributes(cwd) {
     }
 }
 /** Initialize git repository */
-export async function initGit(cwd, visibility, dryRun) {
+export async function initGit(cwd, visibility, dryRun, allowTs) {
     const pkg = readPackageJson(cwd);
     const repoName = pkg.name.replace(/^@[^/]+\//, ''); // Remove scope
     console.log('Initializing git repository...');
@@ -2428,7 +2451,7 @@ export async function initGit(cwd, visibility, dryRun) {
     // Ensure .gitignore exists and includes node_modules
     ensureGitignore(cwd);
     // Ensure .npmignore exists with recommended patterns
-    ensureNpmignore(cwd);
+    ensureNpmignore(cwd, allowTs);
     // Ensure .gitattributes exists for LF line endings
     ensureGitattributes(cwd);
     // git init
@@ -2693,7 +2716,7 @@ async function doLocalInstall(cwd, options) {
 export async function globalize(cwd, options = {}, configOptions = {}) {
     const { bump = 'patch', noPublish = false, cleanup = false, install = false, link = false, wsl = false, force = false, files = true, dryRun = false, quiet = true, verbose = false, init = false, gitVisibility = 'private', npmVisibility = 'private', message, conform = false, asis = false, updateDeps = false, updateMajor = false, publishDeps = true, // Default to publishing deps for safety
     publishDepsYes = false, // -pd: auto-yes to dep-cascade prompts (private only)
-    noPrescan = false, forcePublish = false, fix = true, fixTags = false, rebase = false, show = false, local = false, freeze = false } = options;
+    noPrescan = false, forcePublish = false, fix = true, fixTags = false, rebase = false, show = false, local = false, freeze = false, usePaths = true, allowTs } = options;
     // Show tool version only for recursive dep calls (CLI already prints it at startup)
     const toolVersion = getToolVersion();
     if (!options._fromWorkspace && !options._fromCli) {
@@ -2752,6 +2775,12 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
             settings.push('-local');
         if (configOptions.freeze)
             settings.push('-freeze');
+        if (configOptions.usePaths === false)
+            settings.push('--no-use-paths');
+        if (configOptions.allowTs === true)
+            settings.push('-npm ts');
+        if (configOptions.allowTs === false)
+            settings.push('-npm nts');
         if (settings.length > 0) {
             console.log(colors.dim(`Settings from .globalize.json5: ${settings.join(', ')}`));
         }
@@ -2832,7 +2861,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
     }
     // Check ignore files first (unless cleanup mode)
     if (!cleanup && !asis) {
-        const checkResult = checkIgnoreFiles(cwd, { conform, asis, verbose });
+        const checkResult = checkIgnoreFiles(cwd, { conform, asis, verbose, allowTs });
         // Auto-add security patterns without prompting
         if (checkResult.securityChanges.length > 0) {
             const secGit = [];
@@ -2845,7 +2874,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                     secNpm.push(change.replace('  .npmignore missing: ', '').trim());
                 }
             }
-            conformIgnoreFiles(cwd, true);
+            conformIgnoreFiles(cwd, true, allowTs);
             if (secGit.length > 0) {
                 console.log(colors.cyan('  .gitignore: auto-added ') + secGit.join(', '));
             }
@@ -2876,7 +2905,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
             console.log('');
             if (conform) {
                 console.log('Applying changes (--conform)...');
-                conformIgnoreFiles(cwd);
+                conformIgnoreFiles(cwd, false, allowTs);
                 console.log('');
             }
             else {
@@ -2888,7 +2917,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 const choice = await promptChoice('Your choice [ok/asis/abort]:', ['ok', 'asis', 'abort']);
                 if (choice === 'ok') {
                     console.log('Applying changes...');
-                    conformIgnoreFiles(cwd);
+                    conformIgnoreFiles(cwd, false, allowTs);
                     console.log(colors.green('✓ Ignore files updated'));
                     console.log('');
                 }
@@ -2946,13 +2975,13 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 options.autoInit = true;
             }
             // choice is '1', 'a', or '' (default)
-            const success = await initGit(cwd, gitVisibility, dryRun);
+            const success = await initGit(cwd, gitVisibility, dryRun, allowTs);
             if (!success)
                 return false;
             justInitialized = true;
         }
         else {
-            const success = await initGit(cwd, gitVisibility, dryRun);
+            const success = await initGit(cwd, gitVisibility, dryRun, allowTs);
             if (!success)
                 return false;
             justInitialized = true;
@@ -2975,7 +3004,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 options.autoInit = true;
             }
         }
-        const success = await initGit(cwd, gitVisibility, dryRun);
+        const success = await initGit(cwd, gitVisibility, dryRun, allowTs);
         if (!success)
             return false;
         justInitialized = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.154",
+  "version": "1.0.155",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",