bestzip 3.0.2 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/cli.js CHANGED
@@ -5,7 +5,13 @@ import * as bestzip from "../lib/bestzip.js";
5
5
  import yargs from "yargs";
6
6
  import { hideBin } from "yargs/helpers";
7
7
 
8
- const argv = yargs(hideBin(process.argv))
8
+ // Rewrite -0 … -9 into --level 0 … --level 9 before yargs parses them
9
+ const preprocessed = hideBin(process.argv).flatMap((arg) => {
10
+ const match = /^-([0-9])$/.exec(arg);
11
+ return match ? ["--level", match[1]] : [arg];
12
+ });
13
+
14
+ const argv = yargs(preprocessed)
9
15
  .usage("\nUsage: bestzip destination.zip sources/")
10
16
  .option("force", {
11
17
  describe: "Force use of node.js or native zip methods",
@@ -14,18 +20,17 @@ const argv = yargs(hideBin(process.argv))
14
20
  .option("level", {
15
21
  describe: "Level of compression",
16
22
  type: "number",
17
- default: -1,
23
+ })
24
+ .option("follow-sym-links", {
25
+ describe:
26
+ "Follow symbolic links and include their target contents in the archive",
27
+ type: "boolean",
18
28
  })
19
29
  .demand(2).argv;
20
30
 
21
31
  const destination = argv._.shift();
22
32
  const source = argv._;
23
33
 
24
- if (argv.level < -1 || argv.level > 9) {
25
- console.error("Invalid compression level, must be >= 0 and <= 9");
26
- process.exit(1);
27
- }
28
-
29
34
  console.log("Writing %s to %s...", source.join(", "), destination);
30
35
 
31
36
  let zip;
@@ -43,6 +48,8 @@ zip({
43
48
  destination,
44
49
  verbose: !!argv.verbose,
45
50
  level: argv.level,
51
+ followSymLinks: argv.followSymLinks,
52
+ viaCli: true,
46
53
  })
47
54
  .then(function () {
48
55
  console.log("zipped!");
package/lib/bestzip.js CHANGED
@@ -1,9 +1,11 @@
1
1
  // creates a zip file using either the native `zip` command if available,
2
2
  // or a node.js zip implementation otherwise.
3
3
 
4
- import cp from "node:child_process";
4
+ import cp, { spawnSync } from "node:child_process";
5
5
  import fs from "node:fs";
6
+ import fsp from "node:fs/promises";
6
7
  import path from "node:path";
8
+ import os from "node:os";
7
9
 
8
10
  import { ZipArchive } from "archiver";
9
11
  import { glob, hasMagic } from "glob";
@@ -13,6 +15,44 @@ function hasNativeZip() {
13
15
  return Boolean(which.sync("zip", { nothrow: true }));
14
16
  }
15
17
 
18
+ let nativeSymlinkCapability;
19
+
20
+ // The native zip command needs the --symlinks flag to store symlinks as links
21
+ // rather than following them. Not every build supports it (notably the
22
+ // Windows build of Info-ZIP). This probes the installed zip for support, since
23
+ // the version string isn't a reliable indicator.
24
+ function nativeZipSupportsSymlinks() {
25
+ if (nativeSymlinkCapability !== undefined) {
26
+ return nativeSymlinkCapability;
27
+ }
28
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bestzip-symlink-check"));
29
+ try {
30
+ const file = path.join(dir, "file");
31
+ const link = path.join(dir, "link");
32
+ fs.writeFileSync(file, "bestzip symlink check");
33
+ try {
34
+ fs.symlinkSync("file", link);
35
+ } catch (e) {
36
+ nativeSymlinkCapability = false;
37
+ return nativeSymlinkCapability;
38
+ }
39
+ const res = spawnSync(
40
+ "zip",
41
+ ["-q", "--symlinks", "check.zip", "file", "link"],
42
+ {
43
+ cwd: dir,
44
+ encoding: "utf8",
45
+ }
46
+ );
47
+ nativeSymlinkCapability = res.status === 0;
48
+ } catch (e) {
49
+ nativeSymlinkCapability = false;
50
+ } finally {
51
+ fs.rmSync(dir, { recursive: true, force: true });
52
+ }
53
+ return nativeSymlinkCapability;
54
+ }
55
+
16
56
  async function expandSources(cwd, source) {
17
57
  // options to behave more like the native zip's glob support
18
58
  const globOpts = {
@@ -46,36 +86,129 @@ async function expandSources(cwd, source) {
46
86
  }
47
87
  }
48
88
 
49
- function walkDir(fullPath) {
50
- const files = fs.readdirSync(fullPath).map((f) => {
51
- const filePath = path.join(fullPath, f);
52
- const stats = fs.statSync(filePath);
53
- if (stats.isDirectory()) {
54
- return walkDir(filePath);
55
- }
56
- return filePath;
57
- });
58
- return files.reduce((acc, cur) => acc.concat(cur), []);
89
+ async function walkTree(fullPath, followSymLinks) {
90
+ let stats;
91
+ if (followSymLinks) {
92
+ stats = await fsp.stat(fullPath);
93
+ } else {
94
+ stats = await fsp.lstat(fullPath);
95
+ }
96
+ if (stats.isSymbolicLink() || !stats.isDirectory()) {
97
+ return [{ path: fullPath, stats }];
98
+ }
99
+ const entries = await fsp.readdir(fullPath);
100
+ const children = await Promise.all(
101
+ entries.map((entry) => walkTree(path.join(fullPath, entry), followSymLinks))
102
+ );
103
+ return children.flat();
104
+ }
105
+
106
+ // Validates the compression level. A level of exactly 0-9 (an integer) is
107
+ // accepted; anything else that is set causes an error. An unset level is
108
+ // allowed and left to each implementation's default.
109
+ function validateLevel(level) {
110
+ if (typeof level === "undefined") {
111
+ return;
112
+ }
113
+ if (
114
+ typeof level !== "number" ||
115
+ !Number.isInteger(level) ||
116
+ level < 0 ||
117
+ level > 9
118
+ ) {
119
+ const typehint = typeof level === "number" ? "" : ` (${typeof level})`;
120
+ throw new Error(
121
+ `bestzip: level should be an integer from 0 to 9, got ${level}${typehint}`
122
+ );
123
+ }
124
+ }
125
+
126
+ async function detectSymlinks(cwd, sources) {
127
+ const results = await Promise.all(
128
+ sources.map(async (source) => {
129
+ const fullPath = path.resolve(cwd, source);
130
+ const entries = await walkTree(fullPath, false);
131
+ return entries
132
+ .filter((entry) => entry.stats.isSymbolicLink())
133
+ .map((entry) => entry.path);
134
+ })
135
+ );
136
+ return results.flat();
137
+ }
138
+
139
+ function maybeWarnAboutSymlinks(options, symlinks, cwd) {
140
+ if (options.followSymLinks !== undefined || symlinks.length === 0) {
141
+ return;
142
+ }
143
+ const cli = options.viaCli;
144
+ const optIn = cli ? "pass --follow-sym-links" : "set followSymLinks: true";
145
+ const optOut = cli
146
+ ? "pass --no-follow-sym-links"
147
+ : "set followSymLinks: false";
148
+ let lines = symlinks.map((p) => path.relative(cwd, p));
149
+ if (lines.length > 4) {
150
+ lines = lines.slice(0, 3);
151
+ lines.push(`...and ${symlinks.length - 3} more`);
152
+ }
153
+ console.warn(
154
+ "Warning: Symbolic links are followed by default — their target contents are included in the archive.\n" +
155
+ `To keep this behavior and prevent this warning, ${optIn}.\n` +
156
+ `To store symlinks as links instead, ${optOut}.\n` +
157
+ "This default will change in v4 to store symlinks as links. " +
158
+ "Set followSymLinks explicitly to opt in to following.\n" +
159
+ "Detected symlinks:\n" +
160
+ lines.join("\n")
161
+ );
59
162
  }
60
163
 
61
164
  const nativeZip = async (options) => {
62
165
  const cwd = options.cwd || process.cwd();
63
166
  const command = "zip";
64
167
  const sources = await expandSources(cwd, options.source);
168
+ const destination = path.resolve(cwd, options.destination);
169
+ validateLevel(options.level);
170
+ // followSymLinks: false opts into storing symlinks as links; the default
171
+ // (unset or true) follows symlinks and is unchanged.
172
+ const followSymLinks = options.followSymLinks !== false;
65
173
 
66
- const args = ["--quiet", "--recurse-paths", options.destination, "--"].concat(
67
- sources
68
- );
69
- if (
70
- typeof options.level == "number" &&
71
- !isNaN(options.level) &&
72
- options.level >= 0 &&
73
- options.level <= 9
74
- ) {
75
- args.splice(0, 0, "-" + options.level.toString());
174
+ if (!followSymLinks && !nativeZipSupportsSymlinks()) {
175
+ // The native zip command cannot store symlinks as links on this platform
176
+ // (e.g. the Windows build of Info-ZIP). nodeZip can, so the bestzip()
177
+ // entry point routes accordingly — but a direct nativeZip() call can't
178
+ // fulfill this request.
179
+ throw new Error(
180
+ "The native zip command on this platform cannot store symlinks as links. Use the bestzip() entry point, which will select the node implementation, or set followSymLinks to true to follow symlinks instead."
181
+ );
182
+ }
183
+
184
+ const args = ["--quiet", "--recurse-paths"];
185
+ if (typeof options.level === "number") {
186
+ args.push("-" + options.level.toString());
76
187
  }
188
+ if (!followSymLinks) {
189
+ args.push("--symlinks");
190
+ }
191
+ args.push(destination, "--", ...sources);
192
+
193
+ // Scan for symlinks to warn about in parallel with the zip command. The
194
+ // scan is best-effort: if it fails (e.g. it races the zip command touching
195
+ // the same paths), log and fall back to no warning rather than aborting the
196
+ // zip, and never let it reject before the zip process has completed.
197
+ const warnScan = (async () => {
198
+ if (options.followSymLinks !== undefined) {
199
+ return [];
200
+ }
201
+ try {
202
+ return await detectSymlinks(cwd, sources);
203
+ } catch (err) {
204
+ console.warn(
205
+ `bestzip: failed to scan for symlinks to warn about: ${err.message}`
206
+ );
207
+ return [];
208
+ }
209
+ })();
77
210
 
78
- return new Promise((resolve, reject) => {
211
+ const zipPromise = new Promise((resolve, reject) => {
79
212
  const zipProcess = cp.spawn(command, args, {
80
213
  stdio: "inherit",
81
214
  cwd,
@@ -95,18 +228,34 @@ const nativeZip = async (options) => {
95
228
  }
96
229
  });
97
230
  });
231
+
232
+ const [symlinks] = await Promise.all([warnScan, zipPromise]);
233
+ maybeWarnAboutSymlinks(options, symlinks, cwd);
98
234
  };
99
235
 
100
236
  // based on http://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js/18775083#18775083
101
237
  const nodeZip = async (options) => {
102
238
  const cwd = options.cwd || process.cwd();
103
- const output = fs.createWriteStream(path.resolve(cwd, options.destination));
239
+ validateLevel(options.level);
240
+ // followSymLinks: false stores symlinks as links; the default (unset or
241
+ // true) follows symlinks, matching the native zip implementation.
242
+ const followSymLinks = options.followSymLinks !== false;
243
+ const symlinks = [];
244
+ const outputFile = await fsp.open(
245
+ path.resolve(cwd, options.destination),
246
+ "w"
247
+ );
248
+ const output = outputFile.createWriteStream();
104
249
  const archive = new ZipArchive({
105
250
  zlib: { level: options.level },
106
251
  });
107
252
 
108
- output.on("close", () => resolvePromise());
253
+ output.on("close", async () => {
254
+ await outputFile.close();
255
+ resolvePromise();
256
+ });
109
257
  archive.on("error", (err) => rejectPromise(err));
258
+ archive.on("warning", (err) => console.warn(err && err.message));
110
259
 
111
260
  archive.pipe(output);
112
261
 
@@ -121,26 +270,57 @@ const nodeZip = async (options) => {
121
270
  const fullPath = path.resolve(cwd, source);
122
271
  const destPath = source;
123
272
 
124
- const stats = await fs.promises.stat(fullPath);
125
- if (stats.isDirectory()) {
126
- // Walk directory. Works on directories and directory symlinks.
127
- const files = walkDir(fullPath);
128
- files.forEach((f) => {
129
- const subPath = f.substring(fullPath.length);
130
- archive.file(f, {
131
- name: destPath + subPath,
132
- });
273
+ if (!followSymLinks) {
274
+ // Store symlinks as link entries (their targets, not their contents).
275
+ const entries = await walkTree(fullPath, false);
276
+ for (const entry of entries) {
277
+ const subPath = entry.path.substring(fullPath.length);
278
+ if (entry.stats.isSymbolicLink()) {
279
+ symlinks.push(entry.path);
280
+ archive.symlink(
281
+ destPath + subPath,
282
+ await fsp.readlink(entry.path),
283
+ entry.stats.mode
284
+ );
285
+ } else {
286
+ archive.file(entry.path, {
287
+ name: destPath + subPath,
288
+ stats: entry.stats,
289
+ });
290
+ }
291
+ }
292
+ return;
293
+ }
294
+
295
+ // Follow symlinks by default. Pass explicit (stat) stats so archiver
296
+ // dereferences symlinks and stores their target contents rather than the
297
+ // link itself, matching the native zip implementation.
298
+ const entries = await walkTree(fullPath, true);
299
+ for (const entry of entries) {
300
+ const archiveName = destPath + entry.path.substring(fullPath.length);
301
+ archive.file(entry.path, {
302
+ name: archiveName,
303
+ stats: entry.stats,
133
304
  });
134
- } else if (stats.isFile()) {
135
- archive.file(fullPath, { stats: stats, name: destPath });
305
+ }
306
+
307
+ // Warn while following by default (followSymLinks unset): detect symlinks
308
+ // via an lstat walk so the deprecation warning still fires even though the
309
+ // archive stores their target contents.
310
+ if (options.followSymLinks === undefined) {
311
+ const detected = await walkTree(fullPath, false);
312
+ for (const entry of detected) {
313
+ if (entry.stats.isSymbolicLink()) {
314
+ symlinks.push(entry.path);
315
+ }
316
+ }
136
317
  }
137
318
  }
138
319
 
139
320
  try {
140
321
  const expandedSources = await expandSources(cwd, options.source);
141
- for (const source of expandedSources) {
142
- await addSource(source);
143
- }
322
+ await Promise.all(expandedSources.map(addSource));
323
+ maybeWarnAboutSymlinks(options, symlinks, cwd);
144
324
  archive.finalize();
145
325
  } catch (err) {
146
326
  rejectPromise(err);
@@ -158,8 +338,16 @@ function zip(options) {
158
338
  };
159
339
  }
160
340
 
341
+ // The native zip command can store symlinks as links only when it supports
342
+ // --symlinks. If followSymLinks is not explicitly false, it just follows
343
+ // symlinks, which every native zip can do. When storing links is requested
344
+ // but the native zip can't do it, fall back to the node implementation.
345
+ const useNative =
346
+ hasNativeZip() &&
347
+ (options.followSymLinks !== false || nativeZipSupportsSymlinks());
348
+
161
349
  let promise;
162
- if (hasNativeZip()) {
350
+ if (useNative) {
163
351
  promise = nativeZip(options);
164
352
  } else {
165
353
  promise = nodeZip(options);
@@ -174,4 +362,4 @@ function zip(options) {
174
362
 
175
363
  export default zip;
176
364
 
177
- export { zip, nodeZip, nativeZip, hasNativeZip };
365
+ export { zip, nodeZip, nativeZip, hasNativeZip, nativeZipSupportsSymlinks };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bestzip",
3
- "version": "3.0.2",
3
+ "version": "3.1.0",
4
4
  "description": "Uses OS zip command if available (for better performance and speed) or node.js version if there is no system command available. Can be called via node or command line.",
5
5
  "type": "module",
6
6
  "exports": "./lib/bestzip.js",
package/readme.md CHANGED
@@ -16,7 +16,7 @@ The native `zip` command on GNU/Linux and macOS is significantly faster and crea
16
16
  ## Global command line usage
17
17
 
18
18
  npm install -g bestzip
19
- bestzip destination.zip source/ [other sources...]
19
+ bestzip --no-follow-sym-links destination.zip source/ [other sources...]
20
20
 
21
21
  ## Command line usage within `package.json` scripts
22
22
 
@@ -28,42 +28,63 @@ package.json:
28
28
  {
29
29
  //...
30
30
  "scripts": {
31
- "build" "...",
32
- "zip": "bestzip bundle.zip build/*",
31
+ "build": "...",
32
+ "zip": "bestzip --no-follow-sym-links bundle.zip build/*",
33
33
  "upload": "....",
34
34
  "deploy": "npm run build && npm run zip && npm run upload"
35
35
  }
36
36
  }
37
37
  ```
38
38
 
39
+ ## Command line options
40
+
41
+ * `--follow-sym-links` / `--no-follow-sym-links`: Follow symbolic links and include their target contents in the archive (the default) or don't follow and instead include the link itself. Setting one flag or the other is recommended because the default will change in the next major version (v4.0.0). If symlinks are encountered when the flag is not set, a warning will be logged.
42
+ * `--level N` / `-N`: Level of compression, as with the native `zip` command. `N` must be an integer from 0 (store, no compression) to 9 (maximum compression). Defaults to each implementation's own default when unset.
43
+ * `--force node|native`: Force the Node.js implementation or the native `zip` command instead of letting bestzip pick automatically.
44
+
45
+
39
46
  ## Programmatic usage from within Node.js
40
47
 
41
48
  ```javascript
42
- import zip from 'bestzip';
43
- // use version 2.x for require()
49
+ import { zip } from 'bestzip';
50
+ // const { zip } = require('bestzip'); // for CJS (requires node.js v22 or newer
44
51
 
45
52
  // zip a single source
46
53
  await zip({
47
54
  source: 'build/*',
48
- destination: './destination.zip'
55
+ destination: './destination.zip',
56
+ followSymLinks: false,
49
57
  })
50
58
 
51
59
  // zip multiple sources, starting in a different CWD (current working directory)
52
60
  await zip({
53
61
  source: ['img1.jpg', 'img2.jpg', 'imgn.jpg'],
54
62
  destination: '../images.zip',
55
- cwd: './images/' // optional, defaults to process.cwd()
63
+ cwd: './images/', // optional, defaults to process.cwd()
64
+ followSymLinks: false,
56
65
  })
57
66
 
58
67
  // Promises also work: zip({source, destination}).then(...).catch(...)
59
68
  // Callbacks also work: zip(destination, sources, callback)
60
69
  ```
61
70
 
62
- ### Options
71
+ ### API Options
63
72
 
64
73
  * `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
65
74
  * `destination`: Path to generated .zip file.
66
75
  * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
76
+ * `level`: Level of compression, as with the native `zip` command. An integer from 0 (store, no compression) to 9 (maximum compression). Defaults to each implementation's own default when unset.
77
+ * `followSymLinks`: Follow symbolic links and include the contents of their targets in the zip file. When set to `true` or `false` the preference is honored and no warning is printed. When left unset, symbolic links are followed (the current default) and a warning is printed whenever symlinks are detected, because this default will change in v4 to store symlinks as links instead (see [Symbolic links](#symbolic-links)).
78
+
79
+ ## Symbolic links
80
+
81
+ By default, bestzip **follows** symbolic links — their target contents are included in the archive. When symlinks are present and the `followSymLinks` option has not been set explicitly, bestzip prints a warning to stderr listing the symlinked paths and how to opt in or out.
82
+
83
+ **This default will change in v4** to store symlinks as link entries (not following them), which is the more secure behavior. To prepare for this, set `followSymLinks` explicitly in your code.
84
+
85
+ To follow symlinks (the current default), set `followSymLinks: true` (programmatic API) or pass `--follow-sym-links` on the command line. To suppress the warning while keeping the current default, set `followSymLinks: true` explicitly. To store symlinks as links instead, set `followSymLinks: false` or pass `--no-follow-sym-links` on the command line.
86
+
87
+ When storing symlinks as links, bestzip uses the native `zip` command when available. Some native `zip` builds (notably the Windows build of Info-ZIP) cannot store symlinks as link entries at all, so bestzip falls back to its built-in Node.js implementation in that case. Note that calling `bestzip.nativeZip` directly with `followSymLinks` unset/false on such a platform throws an error; use the `bestzip()` entry point, which routes to the Node.js implementation automatically. Use `bestzip.nativeZipSupportsSymlinks()` to check whether the available native `zip` can store symlinks as links; it returns `true`/`false` and caches its result after the first call. `bestzip.hasNativeZip()` checks whether a native `zip` is installed at all.
67
88
 
68
89
  ## How to control the directory structure
69
90
 
@@ -90,11 +111,3 @@ Wildcards (`*`) ignore dotfiles.
90
111
  * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
91
112
  * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
92
113
 
93
- ## Breaking changes for v2
94
-
95
- * `bestzip output.zip foo/bar/file.txt` now includes the foo/bar/ folders, previously it would place file.txt at the top-level
96
- * This was done to more closely align with the native zip command
97
-
98
- ## Breaking changes for v3
99
-
100
- * Switched from CJS to ESM