ts-node-pack 0.1.3 → 0.2.0

package/README.md

@@ -25,18 +25,19 @@ Requires Node ≥ 20 and TypeScript ≥ 5.7 available in the package being packe
 ## Usage
 
 ```sh
-ts-node-pack <packageDir> [--tsconfig <path>] [--emit-only] [--keep-temp] [--verbose]
+ts-node-pack <packageDir> [--tsconfig <path>] [--stage-to <dir>] [--skip-pack] [--force] [--verbose]
 ```
 
 | Flag                | Description                                                                                  |
 | ------------------- | -------------------------------------------------------------------------------------------- |
 | `--tsconfig <path>` | tsconfig to extend. Defaults to `tsconfig.build.json` if present, otherwise `tsconfig.json`. |
-| `--emit-only`       | Run emit + rewrites + validation, but skip `npm pack`. Prints the staging directory.         |
-| `--keep-temp`       | Do not delete the temporary staging directory on exit.                                       |
+| `--stage-to <dir>`  | Stage into `<dir>` instead of an auto-created temp dir. Caller owns its lifecycle.           |
+| `--skip-pack`       | Skip the final `npm pack` step. Requires `--stage-to`.                                       |
+| `--force`           | With `--stage-to`, clear `<dir>` if it already has contents.                                 |
 | `-v`, `--verbose`   | Log each pipeline phase to stderr.                                                           |
 | `-h`, `--help`      | Show help.                                                                                   |
 
-The resulting `<name>-<version>.tgz` is written to the current working directory.
+The resulting `<name>-<version>.tgz` is written to the current working directory (unless `--skip-pack` is set).
 
 ### Example
 
@@ -46,20 +47,35 @@ ts-node-pack ./packages/core --verbose
 npm install ./my-core-1.2.3.tgz
 ```
 
+### `--stage-to` and `--skip-pack`
+
+By default `ts-node-pack` stages into an auto-created `mkdtemp()` directory, runs `npm pack` against it, copies the resulting `.tgz` to the current working directory, and removes the temp dir.
+
+Pass `--stage-to <dir>` when you want to keep the staged contents — for example, to let another tool pack from that directory instead (`lerna publish --contents <dir>`, an alternate tarball builder, etc.). `<dir>` must either not exist, be empty, or be opted-in for clearing via `--force`.
+
+Combine with `--skip-pack` to stop after staging and never run `npm pack` at all. `--skip-pack` is only valid with `--stage-to` (otherwise the staged contents would have no accessible location).
+
+| Invocation                                        | Behavior                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| `ts-node-pack <pkg>`                              | Stage to temp dir, pack, copy `.tgz` to CWD, delete temp dir.       |
+| `ts-node-pack <pkg> --stage-to <dir>`             | Stage to `<dir>`, pack, copy `.tgz` to CWD, leave `<dir>` in place. |
+| `ts-node-pack <pkg> --stage-to <dir> --skip-pack` | Stage to `<dir>`, skip pack, leave `<dir>` in place.                |
+| `ts-node-pack <pkg> --skip-pack`                  | Error: `skipPack requires stageTo`.                                 |
+
 ## Pipeline
 
 1. **Resolve package** — read `package.json`, pick tsconfig.
-2. **Stage** — create `mkdtemp()/package/`.
-3. **Derived tsconfig** — write `tsconfig.emit.json` _inside the temp dir_ that `extends` the chosen tsconfig (by absolute path) and forces `outDir`, `declaration`, `rewriteRelativeImportExtensions: true`, `noEmit: false`. If the base tsconfig enables `sourceMap`, `inlineSourceMap`, or `declarationMap`, `inlineSources: true` is also set so debuggers get full source-level fidelity without any `.ts` files in the tarball.
+2. **Stage** — use `--stage-to <dir>` if given, otherwise create `mkdtemp()/package/`. A small separate `mkdtemp()` work dir always holds auxiliary files (e.g. the derived tsconfig) so they never land in the packed contents.
+3. **Derived tsconfig** — write `tsconfig.emit.json` _inside the work dir_ that `extends` the chosen tsconfig (by absolute path) and forces `outDir`, `declaration`, `rewriteRelativeImportExtensions: true`, `noEmit: false`. If the base tsconfig enables `sourceMap`, `inlineSourceMap`, or `declarationMap`, `inlineSources: true` is also set so debuggers get full source-level fidelity without any `.ts` files in the tarball.
 4. **Emit** — run `tsc -p` against the derived config.
 5. **Rewrite `.d.ts`** — for each emitted `.d.ts`, rewrite `./foo.ts` → `./foo.js` in `import` / `export from` / dynamic `import()` specifiers. Non-relative specifiers are left alone.
 6. **Rewrite `package.json`** — rewrite `.ts` → `.js` (and → `.d.ts` under `types` conditions) in `main`, `module`, `types`, `typings`, `bin`, `exports`, and the `files` array. Strip `devDependencies` and `scripts`.
 7. **Copy assets** — `README*`, `LICENSE*`, `CHANGELOG*`, `NOTICE*`. Source `.ts` files are never copied.
 8. **Validate** — fail if any `.ts` specifier remains in emitted `.js` / `.d.ts` / `package.json`, or if a referenced entry point does not exist.
-9. **Pack** — `npm pack` in the staging directory; move the tarball to the original CWD.
-10. **Cleanup** — remove `.ts-node-pack/` and the temp directory (unless `--keep-temp`).
+9. **Pack** — unless `--skip-pack`: `npm pack` in the staging directory and move the tarball to the original CWD.
+10. **Cleanup** — always remove the work dir. In default mode this also removes the staging dir (which is nested inside). In `--stage-to` mode the staging dir is the caller's, and survives.
 
-The source tree is never mutated. All intermediate artifacts (derived tsconfig, staging dir, tarball) live under a single `mkdtemp()` directory that is removed on exit.
+The source tree is never mutated.
 
 ### Sourcemaps
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-node-pack",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Pack a TypeScript package into a Node-compatible npm tarball without modifying the source tree",
   "keywords": [
     "cli",

package/src/cli.js

@@ -8,8 +8,9 @@ const { values, positionals } = parseArgs({
   allowPositionals: true,
   options: {
     tsconfig: { type: "string" },
-    "emit-only": { type: "boolean", default: false },
-    "keep-temp": { type: "boolean", default: false },
+    "skip-pack": { type: "boolean", default: false },
+    "stage-to": { type: "string" },
+    force: { type: "boolean", default: false },
     verbose: { type: "boolean", short: "v", default: false },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -20,10 +21,12 @@ if (values.help || positionals.length === 0) {
 
 Options:
   --tsconfig <path>   Path to tsconfig (default: tsconfig.build.json or tsconfig.json)
-  --emit-only         Emit compiled files without packing
-  --keep-temp         Keep temporary staging directory
-  -v, --verbose       Verbose output
-  -h, --help          Show this help message
+  --stage-to <dir>    Stage into <dir> instead of an auto-created temp dir.
+                      Caller owns cleanup. Errors if <dir> is non-empty unless --force.
+  --skip-pack         Skip the final \`npm pack\` step. Requires --stage-to.
+  --force             With --stage-to, clear <dir> if it already has contents.
+  -v, --verbose       Log each pipeline phase to stderr.
+  -h, --help          Show this help message.
 `);
   process.exit(values.help ? 0 : 1);
 }
@@ -33,8 +36,9 @@ const packageDir = resolve(positionals[0]);
 try {
   const result = await tsNodePack(packageDir, {
     tsconfig: values.tsconfig,
-    emitOnly: values["emit-only"],
-    keepTemp: values["keep-temp"],
+    skipPack: values["skip-pack"],
+    stageTo: values["stage-to"],
+    force: values.force,
     verbose: values.verbose,
   });
   console.log(result);

package/src/index.d.ts

@@ -1,12 +1,24 @@
 export interface TsNodePackOptions {
     tsconfig?: string;
-    emitOnly?: boolean;
-    keepTemp?: boolean;
+    /**
+     * Skip the final `npm pack` step. Requires `stageTo` (otherwise there
+     * is no way for the caller to access the staged contents).
+     */
+    skipPack?: boolean;
+    /**
+     * Stage directly into this directory instead of an auto-created temp
+     * dir. Caller owns cleanup. Errors if the directory already has
+     * contents, unless `force` is set.
+     */
+    stageTo?: string;
+    /** With `stageTo`, clear the target directory if it already has contents. */
+    force?: boolean;
     verbose?: boolean;
 }
 /**
  * Main pipeline: pack a TypeScript package into a Node-compatible tarball.
- * Returns the path to the .tgz file (or the staging dir if --emit-only).
+ * Returns the path to the .tgz file, or the staging directory when
+ * `skipPack` is set.
  */
 export declare function tsNodePack(packageDir: string, options?: TsNodePackOptions): Promise<string>;
 /**

package/src/index.js

@@ -21,22 +21,40 @@ const execFileAsync = promisify(execFile);
 
                                     
                     
+     
+                                                                        
+                                                             
+     
                      
-                     
+     
+                                                                       
+                                                                  
+                                     
+     
+                   
+                                                                               
+                  
                     
  
 
 /**
  * Main pipeline: pack a TypeScript package into a Node-compatible tarball.
- * Returns the path to the .tgz file (or the staging dir if --emit-only).
+ * Returns the path to the .tgz file, or the staging directory when
+ * `skipPack` is set.
  */
 export async function tsNodePack(
   packageDir        ,
   options                    = {},
 )                  {
-  const { tsconfig, emitOnly, keepTemp, verbose } = options;
+  const { tsconfig, skipPack, stageTo, force, verbose } = options;
   const log = verbose ? (...args           ) => console.error("[ts-node-pack]", ...args) : () => {};
 
+  if (skipPack && !stageTo) {
+    throw new Error(
+      "skipPack requires stageTo: caller must specify where to put the staged contents",
+    );
+  }
+
   packageDir = resolve(packageDir);
 
   // ── Phase 1: Resolve package ──────────────────────────────────────────
@@ -48,11 +66,34 @@ export async function tsNodePack(
   const tsconfigPath = resolveTsconfig(packageDir, tsconfig);
   if (tsconfigPath) log(`Found tsconfig: ${tsconfigPath}`);
 
-  // ── Phase 2: Create staging directory ─────────────────────────────────
-  log("Phase 2: Creating staging directory...");
-  const tmpDir = await mkdtemp(join(tmpdir(), "ts-node-pack-"));
-  const stagingDir = join(tmpDir, "package");
-  await mkdir(stagingDir, { recursive: true });
+  // ── Phase 2: Create work and staging directories ─────────────────────
+  // We always need a private work dir for auxiliary files (e.g.
+  // tsconfig.emit.json) that MUST NOT land inside the packed contents.
+  // In default mode the staging dir is nested inside the work dir, so
+  // cleaning up the work dir cleans up everything. In stageTo mode the
+  // staging dir is the caller's directory — we still create a small
+  // separate work dir for auxiliary files and rm only that in Phase 10.
+  log("Phase 2: Creating work and staging directories...");
+  const workDir = await mkdtemp(join(tmpdir(), "ts-node-pack-"));
+  let stagingDir        ;
+  if (stageTo) {
+    stagingDir = resolve(stageTo);
+    if (existsSync(stagingDir)) {
+      const entries = await readdir(stagingDir);
+      if (entries.length > 0) {
+        if (!force) {
+          throw new Error(
+            `stageTo directory is not empty: ${stagingDir}. Pass force: true to clear it.`,
+          );
+        }
+        await rm(stagingDir, { recursive: true, force: true });
+      }
+    }
+    await mkdir(stagingDir, { recursive: true });
+  } else {
+    stagingDir = join(workDir, "package");
+    await mkdir(stagingDir, { recursive: true });
+  }
   log(`Staging: ${stagingDir}`);
 
   try {
@@ -100,7 +141,7 @@ export async function tsNodePack(
 
     if (shouldRunTsc) {
       log("Phase 4: Generating derived tsconfig...");
-      const emitConfigPath = join(tmpDir, "tsconfig.emit.json");
+      const emitConfigPath = join(workDir, "tsconfig.emit.json");
       // tsc's typeRoots walk-up starts at the config's directory, so it
       // can't reach packageDir/node_modules/@types from our temp-dir
       // location. Pin typeRoots when that directory exists. (TS 6.0
@@ -187,26 +228,31 @@ export async function tsNodePack(
     await validate(stagingDir, rewrittenPkg, log);
 
     // ── Phase 9: Pack ─────────────────────────────────────────────────────
-    if (!emitOnly) {
+    if (!skipPack) {
       log("Phase 9: Packing...");
       const tgzPath = await pack(stagingDir);
       const tgzName = basename(tgzPath);
       const dest = join(process.cwd(), tgzName);
       await copyFile(tgzPath, dest);
+      // In stageTo mode the whole staging dir survives into the caller's
+      // filesystem, so the intermediate .tgz that `npm pack` wrote in
+      // there would stick around as visible clutter. Remove it. (In
+      // default mode the entire workDir is rm'd in Phase 10, so this
+      // unlink is redundant but harmless.)
+      if (stageTo) await unlink(tgzPath);
       log(`Created: ${dest}`);
       return dest;
     }
 
-    log(`Emit-only mode. Staging directory: ${stagingDir}`);
+    log(`Skip-pack mode. Staging directory: ${stagingDir}`);
     return stagingDir;
   } finally {
     // ── Phase 10: Cleanup ───────────────────────────────────────────────
-    if (!emitOnly && !keepTemp) {
-      log("Phase 10: Cleaning up temp directory...");
-      await rm(tmpDir, { recursive: true, force: true });
-    } else if (keepTemp) {
-      log(`Keeping temp directory: ${tmpDir}`);
-    }
+    // Always rm the work dir. In default mode this also removes the
+    // staging dir (nested inside). In stageTo mode the staging dir is
+    // the caller's directory and survives.
+    log("Phase 10: Cleaning up work directory...");
+    await rm(workDir, { recursive: true, force: true });
   }
 }