Skip to content

Commit 258e5fd

Browse files
wraithgarwraithgar
authored
feat: add allowGit option (#440)
1 parent 4b559c4 commit 258e5fd

3 files changed

Lines changed: 137 additions & 143 deletions

File tree

‎README.md‎

Lines changed: 99 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -21,24 +21,19 @@ pacote.tarball('https://server.com/package.tgz').then(data => {
2121
})
2222
```
2323

24-
`pacote` works with any kind of package specifier that npm can install. If
25-
you can pass it to the npm CLI, you can pass it to pacote. (In fact, that's
26-
exactly what the npm CLI does.)
24+
`pacote` works with any kind of package specifier that npm can install.
25+
If you can pass it to the npm CLI, you can pass it to pacote.
26+
(In fact, that's exactly what the npm CLI does.)
2727

2828
Anything that you can do with one kind of package, you can do with another.
2929

30-
Data that isn't relevant (like a packument for a tarball) will be
31-
simulated.
30+
Data that isn't relevant (like a packument for a tarball) will be simulated.
3231

33-
`prepare` scripts will be run when generating tarballs from `git` and
34-
`directory` locations, to simulate what _would_ be published to the
35-
registry, so that you get a working package instead of just raw source
36-
code that might need to be transpiled.
32+
`prepare` scripts will be run when generating tarballs from `git` and `directory` locations, to simulate what _would_ be published to the registry, so that you get a working package instead of just raw source code that might need to be transpiled.
3733

3834
## CLI
3935

40-
This module exports a command line interface that can do most of what is
41-
described below. Run `pacote -h` to learn more.
36+
This module exports a command line interface that can do most of what is described below. Run `pacote -h` to learn more.
4237

4338
```
4439
Pacote - The JavaScript Package Handler, v10.1.1
@@ -75,112 +70,96 @@ For example '--cache=/path/to/folder' will use that folder as the cache.
7570

7671
## API
7772

78-
The `spec` refers to any kind of package specifier that npm can install.
79-
If you can pass it to the npm CLI, you can pass it to pacote. (In fact,
80-
that's exactly what the npm CLI does.)
73+
The `spec` refers to any kind of [package specifier](npm.im/npm-package-arg) that npm can install.
8174

8275
See below for valid `opts` values.
8376

84-
* `pacote.resolve(spec, opts)` Resolve a specifier like `foo@latest` or
85-
`github:user/project` all the way to a tarball url, tarball file, or git
86-
repo with commit hash.
77+
* `pacote.resolve(spec, opts)` Resolve a specifier like `foo@latest` or `github:user/project` all the way to a tarball url, tarball file, or git repo with commit hash.
8778

88-
* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a
89-
destination folder. Returns a promise that resolves to the
90-
`{from,resolved,integrity}` of the extracted package.
79+
* `pacote.extract(spec, dest, opts)` Extract a package's tarball into a destination folder.
80+
Returns a promise that resolves to the `{from,resolved,integrity}` of the extracted package.
9181

92-
* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest
93-
(basically, the `package.json` file, plus a bit of metadata).
94-
See below for more on manifests and packuments. Returns a Promise that
95-
resolves to the manifest object.
82+
* `pacote.manifest(spec, opts)` Fetch (or simulate) a package's manifest (basically, the `package.json` file, plus a bit of metadata).
83+
See below for more on manifests and packuments.
84+
Returns a Promise that resolves to the manifest object.
9685

97-
* `pacote.packument(spec, opts)` Fetch (or simulate) a package's packument
98-
(basically, the top-level package document listing all the manifests that
99-
the registry returns). See below for more on manifests and packuments.
86+
* `pacote.packument(spec, opts)` Fetch (or simulate) a package's packument (basically, the top-level package document listing all the manifests that the registry returns).
87+
See below for more on manifests and packuments.
10088
Returns a Promise that resolves to the packument object.
10189

10290
* `pacote.tarball(spec, opts)` Get a package tarball data as a buffer in
103-
memory. Returns a Promise that resolves to the tarball data Buffer, with
104-
`from`, `resolved`, and `integrity` fields attached.
91+
memory.
92+
Returns a Promise that resolves to the tarball data Buffer, with `from`, `resolved`, and `integrity` fields attached.
10593

106-
* `pacote.tarball.file(spec, dest, opts)` Save a package tarball data to
107-
a file on disk. Returns a Promise that resolves to
108-
`{from,integrity,resolved}` of the fetched tarball.
94+
* `pacote.tarball.file(spec, dest, opts)` Save a package tarball data to a file on disk.
95+
Returns a Promise that resolves to `{from,integrity,resolved}` of the fetched tarball.
10996

110-
* `pacote.tarball.stream(spec, streamHandler, opts)` Fetch a tarball and
111-
make the stream available to the `streamHandler` function.
97+
* `pacote.tarball.stream(spec, streamHandler, opts)` Fetch a tarball and make the stream available to the `streamHandler` function.
11298

113-
This is mostly an internal function, but it is exposed because it does
114-
provide some functionality that may be difficult to achieve otherwise.
99+
This is mostly an internal function, but it is exposed because it does provide some functionality that may be difficult to achieve otherwise.
115100

116-
The `streamHandler` function MUST return a Promise that resolves when
117-
the stream (and all associated work) is ended, or rejects if the stream
101+
The `streamHandler` function MUST return a Promise that resolves when the stream (and all associated work) is ended, or rejects if the stream
118102
has an error.
119103

120-
The `streamHandler` function MAY be called multiple times, as Pacote
121-
retries requests in some scenarios, such as cache corruption or
122-
retriable network failures.
104+
The `streamHandler` function MAY be called multiple times, as Pacote retries requests in some scenarios, such as cache corruption or retriable network failures.
123105

124106
### Options
125107

126108
Options are passed to
127-
[`npm-registry-fetch`](http://npm.im/npm-registry-fetch) and
128-
[`cacache`](http://npm.im/cacache), so in addition to these, anything for
129-
those modules can be given to pacote as well.
109+
[`npm-registry-fetch`](http://npm.im/npm-registry-fetch) and [`cacache`](http://npm.im/cacache), so in addition to these, anything for those modules can be given to pacote as well.
130110

131-
Options object is cloned, and mutated along the way to add integrity,
132-
resolved, and other properties, as they are determined.
111+
Options object is cloned, and mutated along the way to add integrity, resolved, and other properties, as they are determined.
133112

134-
* `cache` Where to store cache entries and temp files. Passed to
135-
[`cacache`](http://npm.im/cacache). Defaults to the same cache directory
136-
that npm will use by default, based on platform and environment.
113+
* `cache` Where to store cache entries and temp files.
114+
Passed to [`cacache`](http://npm.im/cacache).
115+
Defaults to the same cache directory that npm will use by default, based on platform and environment.
137116
* `where` Base folder for resolving relative `file:` dependencies.
138-
* `resolved` Shortcut for looking up resolved values. Should be specified
139-
if known.
140-
* `integrity` Expected integrity of fetched package tarball. If specified,
141-
tarballs with mismatched integrity values will raise an `EINTEGRITY`
142-
error.
117+
* `resolved` Shortcut for looking up resolved values. Should be specified if known.
118+
* `integrity` Expected integrity of fetched package tarball.
119+
If specified, tarballs with mismatched integrity values will raise an `EINTEGRITY` error.
143120
* `umask` Permission mode mask for extracted files and directories.
144-
Defaults to `0o22`. See "Extracted File Modes" below.
145-
* `fmode` Minimum permission mode for extracted files. Defaults to
146-
`0o666`. See "Extracted File Modes" below.
147-
* `dmode` Minimum permission mode for extracted directories. Defaults to
148-
`0o777`. See "Extracted File Modes" below.
149-
* `preferOnline` Prefer to revalidate cache entries, even when it would not
150-
be strictly necessary. Default `false`.
151-
* `before` When picking a manifest from a packument, only consider
152-
packages published before the specified date. Default `null`.
153-
* `defaultTag` The default `dist-tag` to use when choosing a manifest from a
154-
packument. Defaults to `latest`.
155-
* `registry` The npm registry to use by default. Defaults to
156-
`https://registry.npmjs.org/`.
157-
* `fullMetadata` Fetch the full metadata from the registry for packuments,
158-
including information not strictly required for installation (author,
159-
description, etc.) Defaults to `true` when `before` is set, since the
160-
version publish time is part of the extended packument metadata.
161-
* `fullReadJson` Use the slower `read-package-json` package insted of
162-
`read-package-json-fast` in order to include extra fields like "readme" in
163-
the manifest. Defaults to `false`.
164-
* `packumentCache` For registry packuments only, you may provide a `Map`
165-
object which will be used to cache packument requests between pacote
166-
calls. This allows you to easily avoid hitting the registry multiple
167-
times (even just to validate the cache) for a given packument, since it
168-
is unlikely to change in the span of a single command.
169-
* `verifySignatures` A boolean that will make pacote verify the
170-
integrity signature of a manifest, if present. There must be a
171-
configured `_keys` entry in the config that is scoped to the
172-
registry the manifest is being fetched from.
173-
* `verifyAttestations` A boolean that will make pacote verify Sigstore
174-
attestations, if present. There must be a configured `_keys` entry in the
175-
config that is scoped to the registry the manifest is being fetched from.
176-
* `tufCache` Where to store metadata/target files when retrieving the package
177-
attestation key material via TUF. Defaults to the same cache directory that
178-
npm will use by default, based on platform and environment.
121+
Defaults to `0o22`.
122+
See "Extracted File Modes" below.
123+
* `fmode` Minimum permission mode for extracted files.
124+
Defaults to `0o666`.
125+
See "Extracted File Modes" below.
126+
* `dmode` Minimum permission mode for extracted directories.
127+
Defaults to `0o777`.
128+
See "Extracted File Modes" below.
129+
* `preferOnline` Prefer to revalidate cache entries, even when it would not be strictly necessary.
130+
Defaults to `false`.
131+
* `before` When picking a manifest from a packument, only consider packages published before the specified date.
132+
Defaults to `null`.
133+
* `defaultTag` The default `dist-tag` to use when choosing a manifest from a packument.
134+
Defaults to `latest`.
135+
* `registry` The npm registry to use by default.
136+
Defaults to `https://registry.npmjs.org/`.
137+
* `fullMetadata` Fetch the full metadata from the registry for packuments, including information not strictly required for installation (author, description, etc.).
138+
Defaults to `true` when `before` is set, since the version publish time is part of the extended packument metadata.
139+
Otherwise defaults to `false`.
140+
* `fullReadJson` Use the slower `read-package-json` package insted of `read-package-json-fast` in order to include extra fields like "readme" in the manifest.
141+
Defaults to `false`.
142+
* `packumentCache` For registry packuments only, you may provide a `Map` object which will be used to cache packument requests between pacote calls.
143+
This allows you to easily avoid hitting the registry multiple times (even just to validate the cache) for a given packument, since it is unlikely to change in the span of a single command.
144+
* `verifySignatures` A boolean that will make pacote verify the integrity signature of a manifest, if present.
145+
There must be a configured `_keys` entry in the config that is scoped to the registry the manifest is being fetched from.
146+
* `verifyAttestations` A boolean that will make pacote verify Sigstore attestations, if present.
147+
There must be a configured `_keys` entry in the config that is scoped to the registry the manifest is being fetched from.
148+
* `tufCache` Where to store metadata/target files when retrieving the package attestation key material via TUF.
149+
Defaults to the same cache directory that npm will use by default, based on platform and environment.
150+
* `allowGit` Whether or not to allow data to be fetched from git.
151+
Possible values are `all`, `none`, or `root`.
152+
Defaults to `all`.
153+
`all` means git is allowed
154+
`none` means git is not allowed
155+
`root` means that git is only allowed if fetching from a root context.
156+
Context for whether or not the package being fetched is `root` is set via the `_isRoot` option.
157+
* `_isRoot` Whether or not the package being fetched is in a root context.
158+
For `npm` itself this means a package that is defined in the local project or workspace package.json, or a package that is being fetched for another command like `npm view`.
179159

180160
### Advanced API
181161

182-
Each different type of fetcher is exposed for more advanced usage such as
183-
using helper methods from this classes:
162+
Each different type of fetcher is exposed for more advanced usage such as using helper methods from this classes:
184163

185164
* `DirFetcher`
186165
* `FileFetcher`
@@ -196,87 +175,66 @@ Files are extracted with a mode matching the following formula:
196175
( (tarball entry mode value) | (minimum mode option) ) ~ (umask)
197176
```
198177

199-
This is in order to prevent unreadable files or unlistable directories from
200-
cluttering a project's `node_modules` folder, even if the package tarball
201-
specifies that the file should be inaccessible.
178+
This is in order to prevent unreadable files or unlistable directories from cluttering a project's `node_modules` folder, even if the package tarball specifies that the file should be inaccessible.
202179

203-
It also prevents files from being group- or world-writable without explicit
204-
opt-in by the user, because all file and directory modes are masked against
205-
the `umask` value.
180+
It also prevents files from being group- or world-writable without explicit opt-in by the user, because all file and directory modes are masked against the `umask` value.
206181

207-
So, a file which is `0o771` in the tarball, using the default `fmode` of
208-
`0o666` and `umask` of `0o22`, will result in a file mode of `0o755`:
182+
So, a file which is `0o771` in the tarball, using the default `fmode` of `0o666` and `umask` of `0o22`, will result in a file mode of `0o755`:
209183

210184
```
211185
(0o771 | 0o666) => 0o777
212186
(0o777 ~ 0o22) => 0o755
213187
```
214188

215-
In almost every case, the defaults are appropriate. To respect exactly
216-
what is in the package tarball (even if this makes an unusable system), set
217-
both `dmode` and `fmode` options to `0`. Otherwise, the `umask` config
218-
should be used in most cases where file mode modifications are required,
219-
and this functions more or less the same as the `umask` value in most Unix
220-
systems.
189+
In almost every case, the defaults are appropriate.
190+
To respect exactly what is in the package tarball (even if this makes an unusable system), set both `dmode` and `fmode` options to `0`.
191+
Otherwise, the `umask` config should be used in most cases where file mode modifications are required, and this functions more or less the same as the `umask` value in most Unix systems.
221192

222193
## Extracted File Ownership
223194

224-
When running as `root` on Unix systems, all extracted files and folders
225-
will have their owning `uid` and `gid` values set to match the ownership
226-
of the containing folder.
195+
When running as `root` on Unix systems, all extracted files and folders will have their owning `uid` and `gid` values set to match the ownership of the containing folder.
227196

228-
This prevents `root`-owned files showing up in a project's `node_modules`
229-
folder when a user runs `sudo npm install`.
197+
This prevents `root`-owned files showing up in a project's `node_modules` folder when a user runs `sudo npm install`.
230198

231199
## Manifests
232200

233-
A `manifest` is similar to a `package.json` file. However, it has a few
234-
pieces of extra metadata, and sometimes lacks metadata that is inessential
235-
to package installation.
201+
A `manifest` is similar to a `package.json` file.
202+
However, it has a few pieces of extra metadata, and sometimes lacks metadata that is inessential to package installation.
236203

237204
In addition to the common `package.json` fields, manifests include:
238205

239-
* `manifest._resolved` The tarball url or file path where the package
240-
artifact can be found.
206+
* `manifest._resolved` The tarball url or file path where the package artifact can be found.
241207
* `manifest._from` A normalized form of the spec passed in as an argument.
242208
* `manifest._integrity` The integrity value for the package artifact.
243209
* `manifest._id` The canonical spec of this package version: name@version.
244-
* `manifest.dist` Registry manifests (those included in a packument) have a
245-
`dist` object. Only `tarball` is required, though at least one of
246-
`shasum` or `integrity` is almost always present.
247-
248-
* `tarball` The url to the associated package artifact. (Copied by
249-
Pacote to `manifest._resolved`.)
250-
* `integrity` The integrity SRI string for the artifact. This may not
251-
be present for older packages on the npm registry. (Copied by Pacote
252-
to `manifest._integrity`.)
210+
* `manifest.dist` Registry manifests (those included in a packument) have a `dist` object.
211+
Only `tarball` is required, though at least one of `shasum` or `integrity` is almost always present.
212+
213+
* `tarball` The url to the associated package artifact.
214+
(Copied by Pacote to `manifest._resolved`.)
215+
* `integrity` The integrity SRI string for the artifact.
216+
This may not be present for older packages on the npm registry.
217+
(Copied by Pacote to `manifest._integrity`.)
253218
* `shasum` Legacy integrity value. Hexadecimal-encoded sha1 hash.
254-
(Converted to an SRI string and copied by Pacote to
255-
`manifest._integrity` when `dist.integrity` is not present.)
219+
(Converted to an SRI string and copied by Pacote to `manifest._integrity` when `dist.integrity` is not present.)
256220
* `fileCount` Number of files in the tarball.
257221
* `unpackedSize` Size on disk of the package when unpacked.
258-
* `signatures` Signatures of the shasum. Includes the keyid that
259-
correlates to a [`key from the npm
260-
registry`](https://registry.npmjs.org/-/npm/v1/keys)
222+
* `signatures` Signatures of the shasum.
223+
Includes the keyid that correlates to a [`key from the npm registry`](https://registry.npmjs.org/-/npm/v1/keys)
261224

262225
## Packuments
263226

264-
A packument is the top-level package document that lists the set of
265-
manifests for available versions for a package.
227+
A packument is the top-level package document that lists the set of manifests for available versions for a package.
266228

267-
When a packument is fetched with `accept:
268-
application/vnd.npm.install-v1+json` in the HTTP headers, only the most
269-
minimum necessary metadata is returned. Additional metadata is returned
270-
when fetched with only `accept: application/json`.
229+
When a packument is fetched with `accept: application/vnd.npm.install-v1+json` in the HTTP headers, only the most minimum necessary metadata is returned.
230+
Additional metadata is returned when fetched with only `accept: application/json`.
271231

272232
For Pacote's purposes, the following fields are relevant:
273233

274-
* `versions` An object where each key is a version, and each value is the
275-
manifest for that version.
276-
* `dist-tags` An object mapping dist-tags to version numbers. This is how
277-
`foo@latest` gets turned into `foo@1.2.3`.
278-
* `time` In the full packument, an object mapping version numbers to
279-
publication times, for the `opts.before` functionality.
234+
* `versions` An object where each key is a version, and each value is the manifest for that version.
235+
* `dist-tags` An object mapping dist-tags to version numbers.
236+
This is how `foo@latest` gets turned into `foo@1.2.3`.
237+
* `time` In the full packument, an object mapping version numbers to publication times, for the `opts.before` functionality.
280238

281239
Pacote adds the following field, regardless of the accept header:
282240

0 commit comments

Comments
 (0)