@projectpac/packages-git

The git package source: a plugin whose bytes come from a repository rather than a registry.

A source brings bytes onto the machine and reports what backs them. It decides nothing about installing: reading the manifest, what the principal is shown, the policy gate, and the tree row all live above the seam in the host.

pac plugins add --package git+https://github.com/someone/flow-thing#v1.2.0
pac plugins add --package git+https://github.com/someone/flow-thing#3f1a...  # a commit

Why this is not a flag on the npm source

npm's own grammar already accepts git urls. The npm source refuses them, because the fetch happens before the principal has been asked anything -- the manifest they will be shown comes out of the package -- so a spec that could name a git host would be a spec that chooses where the fetch reaches. Where a fetch may reach has to be the node's decision.

Installing this package is that decision. Nothing enables it by default, and a node without it cannot be talked into cloning from anywhere.

• Named schemes only. git+https://, git+ssh://, git://, each with an optional #ref. The git+ is a marker for which source serves the spec, not part of the url.
• Shallow, single-branch, no submodules. --depth 1 --no-tags --single-branch, and --recurse-submodules is deliberately absent: a submodule is another url the spec did not name.
• --ignore-scripts on the dependency install. A clone carries no node_modules and a plugin that cannot import the sdk cannot run, so the package's dependencies are installed -- with its hooks refused, because those are code the principal has not agreed to run and has not been shown yet. Dev dependencies are not this node's business.
• Bounded. The clones have a byte ceiling, and a fetch that would cross it is undone before the host reads anything.

Where a clone lands

The host hands every source the node's one module directory -- <data dir>/modules, an npm prefix -- and a package has to end up under its node_modules for the node to load it. A clone renamed straight in there would be a directory npm has no record of, and npm prunes what it has no record of: the npm source's next --save install would take it out again.

So the clone is kept at <data dir>/modules/git/<name>, dependencies installed inside it, and then installed from there as a file: dependency of the prefix. npm writes the row into the prefix's own package.json and links node_modules/<name> at the clone, so a later install of anything else leaves it standing, and the node resolves it the way it resolves everything else in that directory. The two sources never hold the same package twice: what is under node_modules is one tree, whoever put each thing there.

What it can vouch for, and what it cannot

Narrower than npm, and it says so rather than rounding up.

| the spec named | vouched | why | | ----------------- | ---------- | ------------------------------------------------------------------ | | a full commit sha | verified | nobody can move a sha, so the bytes are exactly the ones asked for | | a branch or a tag | missing | both are mutable: what arrived today is not what arrives tomorrow |

missing is unproven, which is not the same as bad -- and the host's requireVouched (a host: { requireVouched: true } row in spine.yml) is how an operator turns "pin the commit or do not install it" into a rule.

Verifying a signed commit or tag is the stronger answer and is not done here. It needs the signer's key in this machine's keyring, which is a trust decision of its own rather than something this package should make on an operator's behalf.