[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AQMSZ5F0852CM6PPKM74BC":3,"skill-same:01M7AQMSZ5F0852CM6PPKM74BC":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7AQMSZ5F0852CM6PPKM74BC","package-manager-registries-and-installation",null,"Use when building or operating a package registry or the install side of a client. Covers the registry API surface, immutability as the single most important property, mutable-release poisoning, namespacing and name allocation, the content-addressed store, the layout problem's four answers (flat, nested, isolated, PnP), multiple versions coexisting, runtime resolution as part of the design, and publishing and authentication — the evolution from API tokens to trusted publishing with OIDC, provenance and attestations, Sigstore, and SLSA.","the-vibey-project\u002Fvibey","the-vibey-project","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F329298758?v=4","01M7AJHGZ9722CTJ4JNQZVRH0Q","the vibey project","01M7AJHGZVMG2K7TGXQ6XFHVG3",5,"MIT","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fpackage-manager-development\u002Fskills\u002Fpackage-manager-registries-and-installation\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: package-manager-registries-and-installation\ndescription: \"Use when building or operating a package registry or the install side of a client. Covers the registry API surface, immutability as the single most important property, mutable-release poisoning, namespacing and name allocation, the content-addressed store, the layout problem's four answers (flat, nested, isolated, PnP), multiple versions coexisting, runtime resolution as part of the design, and publishing and authentication — the evolution from API tokens to trusted publishing with OIDC, provenance and attestations, Sigstore, and SLSA.\"\n---\n\n# Package Manager Development: Registry Design, Cache, Layout, and Linking, Publishing and Authentication\n\n> **Part 2 of 5** of the *Package Manager Development* reference (plugin `package-manager-development`), covering §5–§7. Sibling skills: `package-manager-versioning-and-resolution` (§0–§4), `package-manager-supply-chain-and-workspaces` (§8–§10), `package-manager-ux-ecosystems-and-governance` (§11–§14), `package-manager-reference` (§15–§20). Section numbers are shared across the set; a reference written as §N → `skill` points into that sibling skill.\n>\n> **Currency:** Verified August 2026. See §17 → `package-manager-reference` for the currency snapshot and what goes stale first.\n\n> **How to read this.** Reference, not tutorial. Sections are independent. Three markers:\n> - **[DURABLE]** — computer science, or a lesson every ecosystem has independently learned.\n>   Does not expire.\n> - **[ECOSYSTEM]** — specific to npm, PyPI, crates.io, Go, etc. Verify against that\n>   ecosystem's current docs.\n> - **[CONTESTED]** — the ecosystems have made genuinely different, defensible choices, or\n>   the practitioners disagree. Both cases given.\n>\n> **⚠️ GOTCHA** boxes mark the design mistakes that produce unreproducible builds, wedged\n> caches, exponential resolutions, or supply-chain compromise.\n>\n> **The framing that organizes everything below: a package manager is a distributed\n> systems problem wearing a CLI.** It is a cache-coherency problem, a constraint-solving\n> problem, a trust-and-identity problem, and a compatibility-contract problem, all of\n> which happen to be invoked by typing `install`. Every serious difficulty in this\n> document is one of those four, and treating it as \"just downloading files\" is the root\n> of most bad designs.\n\n---\n\n## §5. Registry Design\n\n### 5.1 The API surface\n\n```\nGET  \u002Fpackages\u002F{name}                  → all versions + metadata (the resolver's hot path)\nGET  \u002Fpackages\u002F{name}\u002F{version}        → one version's metadata\nGET  \u002Fpackages\u002F{name}\u002F{version}\u002Fdl     → the artifact (usually a CDN redirect)\nPOST \u002Fpackages                         → publish (authenticated)\nDELETE \u002F POST \u002Fyank                    → yank\u002Funyank (NOT delete — see 5.2)\nGET  \u002Fsearch, \u002Findex, \u002Fchanges         → discovery and incremental sync\n```\n**Design notes that matter at scale:**\n- **Separate metadata from artifacts.** Metadata is small, hot, highly cacheable, and\n  resolver-critical. Artifacts are large, cold, and belong on a CDN. Conflating them makes\n  resolution slow (§3.6 → `package-manager-versioning-and-resolution`).\n- **Support conditional requests and incremental sync** (`ETag`, `If-None-Match`, a change\n  feed). Mirrors and CI caches depend on it.\n- **Paginate and bound everything.** A package with 10,000 versions must not return a\n  10 MB JSON blob on every resolution step.\n- **Publish upload timestamps** (Python's PEP 700 does) — this is what makes cooldowns\n  possible (§8.4 → `package-manager-supply-chain-and-workspaces`).\n\n### 5.2 Immutability — the single most important registry policy\n\n**[DURABLE] A published (name, version) must never change its bytes.** Consequences of\ngetting this wrong are severe and every ecosystem has learned it, usually the hard way:\n- Caches everywhere become incoherent.\n- Lockfile integrity hashes break for everyone.\n- The `left-pad` incident (2016) — an unpublished package broke thousands of builds —\n  established that **unpublishing must be tightly restricted**.\n\n**The correct primitive is a *yank* (or *quarantine*), not a delete:**\n- Yanked versions remain downloadable so existing lockfiles keep working.\n- They are excluded from *new* resolutions.\n- crates.io, PyPI (quarantine), and npm's deprecate\u002Funpublish windows all converge on this.\n\n**⚠️ And immutability has a security cost you must design for:** Go's `proxy.golang.org`\nand `sum.golang.org` provide extremely strong reproducibility — but that same immutability\nmeans **a malicious module version, once published and cached, persists and continues to be\nserved even after the source repository is removed.** Reproducibility and takedown are in\ndirect tension. Have a documented answer for it.\n\n### 5.3 Mutable-release poisoning — a live design problem\n\nEven with immutable versions, most registries historically allowed **adding new files to an\nexisting release** (e.g. a new wheel for a new Python version, months later). That's a\npoisoning vector: a stolen token lets an attacker add a malicious artifact to a\nlong-trusted release.\n\n**PyPI closed this in July 2026: new files are rejected on releases older than 14 days.**\nThe reasoning is instructive — the change was proposed during PEP 740 discussions in\nJanuary 2024, stalled, and was revived by the **March 2026 LiteLLM and Telnyx\ncompromises**. Before shipping, PyPI measured the impact: of the top 15,000 projects, only\n**56** had uploaded a Python 3.14-compatible wheel more than 14 days after the release\nfirst appeared. Seth Larson's stated rationale is worth internalizing: it prevents releases\nfrom entering \"an indeterminate and confusing state of both compromised and not\ncompromised, where only a subset of files could be poisoned.\"\n\n**[DURABLE] That's the template for registry policy changes: identify the vector, measure\nthe legitimate usage you'd break, publish the numbers, then change the default.**\n\n### 5.4 Namespacing and name allocation\n\n| Model | Example | Trade-off |\n|---|---|---|\n| Flat, first-come | npm (unscoped), PyPI, crates.io | Simple; **land-grab, typosquatting, permanent name exhaustion** |\n| Scoped\u002Fnamespaced | `@org\u002Fpkg` (npm), NuGet prefixes | Ties identity to an owner; reduces squatting |\n| Domain-derived | **Go** (`github.com\u002Fuser\u002Fmod`), Maven (reverse-DNS groupId) | Namespace is *inherited from an existing trust root*. Elegant; couples you to the host |\n| Content-addressed | Nix, Guix | Names are labels, identity is a hash |\n\n**[DURABLE] Go's and Maven's approach — deriving the namespace from a domain or repo you\nalready control — eliminates an entire class of problems** (squatting, name disputes,\nownership transfer ambiguity) at the cost of coupling package identity to a hosting\nprovider. If you're designing new, seriously consider it.\n\nWhatever you choose, you need policy for: name similarity (§8.3 → `package-manager-supply-chain-and-workspaces`), abandoned packages,\nownership transfer, trademark disputes, and reuse of deleted names (**never reuse a name —\nthat's the \"repojacking\" attack**).\n\n---\n\n## §6. Cache, Layout, and Linking\n\n### 6.1 The content-addressed store\n\n**[DURABLE] The right shape for a package cache is a global, content-addressed store.**\n```\n~\u002F.cache\u002Fpm\u002F\n  index\u002F         metadata, keyed by (name, version), immutable → cacheable forever\n  files\u002F         file blobs keyed by content hash (sha256)\n  packages\u002F      package trees, assembled from file blobs\n  tmp\u002F           staging — assemble here, then atomically rename into place\n```\nProperties you get for free: deduplication across projects, integrity verification by\nconstruction, safe concurrent access (a hash-named file either exists and is correct, or\ndoesn't exist), and trivial garbage collection.\n\n**Write atomically**: download to `tmp\u002F`, verify the hash, then `rename()` into place.\nA partially-written cache entry that looks complete is the classic \"wedged cache\" bug that\nusers fix by deleting the whole cache and cursing your name.\n\n**pnpm's contribution** was demonstrating how much this matters: a single content-addressed\nstore hard-linked into each project's `node_modules` means one copy of a given package\nversion on the whole machine, saving developers with many projects tens of gigabytes.\n\n### 6.2 The layout problem — four answers\n\nThis is the JavaScript ecosystem's defining argument, and it generalizes.\n\n| Layout | Mechanism | Ecosystem | Trade-off |\n|---|---|---|---|\n| **Nested** | Each package gets its own `node_modules` | npm v2 | Correct; enormous duplication; Windows path-length failures |\n| **Flat \u002F hoisted** | Everything flattened to the top, conflicts nested | npm v3+, Yarn Classic, Bun (default) | Compact, compatible; **allows phantom dependencies** (§6.3) |\n| **Isolated \u002F symlinked** | Content-addressed store + hardlinks + a symlink tree mirroring the true graph | **pnpm**, **Bun `--linker isolated`** | Strict — packages can only see what they declared; occasional postinstall scripts assume a hoisted shape and break |\n| **No node_modules** | A `.pnp.cjs` map from import to zip archive | **Yarn Berry PnP** | Fastest, strictest, \"zero installs\"; requires runtime cooperation and breaks tools that stat the filesystem |\n\n> **⚠️ GOTCHA — phantom dependencies are a correctness bug, not a style issue.** Under a\n> hoisted layout, `require('lodash')` works even if you never declared lodash, because\n> something else hoisted it to the top. Your code then breaks when that transitive\n> dependency changes — a failure with no visible cause in your own manifest. Strict layouts\n> exist entirely to make this impossible, and **that, not disk space, is their real\n> argument.**\n\n**[DURABLE] The generalizable lesson:** you're choosing between *the real dependency graph*\nand *a flattened approximation that the runtime finds easier*. Flattening is faster and\nmore compatible; it is also lying to the program about what it can see. Ecosystems whose\nruntime resolution is explicit (Python's `sys.path` per-venv, Cargo's compiler-passed\n`--extern`, Go's import paths) never had this problem, because the layout was never the\nlookup mechanism.\n\n### 6.3 Multiple versions coexisting\n\nIf your runtime can load two versions of the same package simultaneously (npm, Cargo), the\nresolver can escape most conflicts (§3.5 → `package-manager-versioning-and-resolution`) — at the cost of duplicated code, larger\nartifacts, and **singleton bugs**. If it can't (Python, Java on one classpath), a conflict\nis fatal and must be reported, which makes resolution failures far more common and your\nerror messages far more important.\n\nCargo's rule is a good middle: **semver-compatible versions are unified into one; semver-\nincompatible versions coexist.** This maximizes deduplication while keeping the escape\nhatch, and the \"expected `foo::Type`, found `foo::Type`\" error is the price.\n\n### 6.4 Runtime resolution is part of your design\n\nThe package manager's job doesn't end at install; the runtime has to find the code.\n- **Node**: directory walk up from the importer, looking for `node_modules` — the reason\n  layout *is* resolution.\n- **Python**: `sys.path`, one environment per virtualenv — flat, one version of anything.\n- **Cargo\u002FRust**: the compiler is passed explicit `--extern` paths — no filesystem search\n  at all, which is why Rust can have two versions of a crate without ambiguity.\n- **Go**: import path includes the major version (`\u002Fv2`) — **semantic import versioning**,\n  so two majors are literally different packages.\n- **JVM**: classpath order; first match wins. The source of endless \"jar hell.\"\n\n**[DURABLE] If you're designing a new ecosystem, make runtime resolution explicit and\nindependent of directory layout.** It removes phantom dependencies, path-length limits,\nand hoisting entirely.\n\n---\n\n## §7. Publishing and Authentication\n\n### 7.1 The evolution, and where it landed\n\n```\nGen 1  username + password                  → phishable, reused, no scoping\nGen 2  long-lived API token                 → phishable, exfiltratable, \"harvest now use later\"\nGen 3  token + 2FA on the account           → helps login, does NOT help a stolen CI token\nGen 4  TRUSTED PUBLISHING (OIDC)            → no long-lived credential exists at all  ★\n       + provenance attestations            → and the artifact proves where it came from\n```\n\n**[DURABLE] Trusted publishing is the current best practice and the direction every major\nregistry has moved.** The mechanism:\n1. The registry pre-registers a trust relationship: \"GitHub Actions workflow\n   `.github\u002Fworkflows\u002Frelease.yml` on repo `org\u002Frepo`, environment `release`, may publish\n   package X.\"\n2. At publish time, CI requests a short-lived **OIDC token** from its provider.\n3. The registry validates the token's claims (repo, workflow, ref\u002Fenvironment) against the\n   registration and issues a **short-lived, minimally-scoped** upload credential.\n4. No long-lived secret is ever stored anywhere.\n\nPyPI shipped this in April 2023; npm added it in response to Shai-Hulud; crates.io has it\nGA. **PEP 807** proposes standardizing the mechanism so *any* Python index can implement\nit, encapsulating PyPI's existing implementation.\n\n**Its explicit security properties**, as PEP 807 states them: credentials are short-lived\nand minimally scoped, limiting blast radius; automatic expiry means **attackers cannot\nmount \"harvest now, use later\" campaigns**; and the upload is conceptually linked to the\nCI identity authorized to perform it.\n\n> **⚠️ GOTCHA — trusted publishing is only as good as its trust configuration.** Trust by\n> *full repository*, not by org or wildcard. Trust by *branch or environment*, not by any\n> ref. A trusted-publishing config that accepts any workflow on any branch is worse than a\n> token, because it looks secure. The 2026 attacks specifically exploited this class of\n> misconfiguration.\n\n### 7.2 Provenance and attestations\n\n**The vocabulary, precisely — people conflate these constantly:**\n- **Provenance** = a *factual claim* about how an artifact was built (source repo, commit,\n  builder, parameters). **On its own it has no integrity properties whatsoever.**\n- **Attestation** = provenance wrapped in a *signed* envelope, so the claim has a\n  cryptographically verifiable author.\n- The dominant envelope is **DSSE** (Dead Simple Signing Envelope); the dominant payload\n  format is an **in-toto statement** with a **SLSA provenance** predicate. \"Attestation\"\n  in 2026 almost always means DSSE + in-toto.\n- **SLSA** describes build integrity *levels*; **Sigstore** is the signing mechanism that\n  makes the claims trustworthy rather than self-asserted text.\n\n**Sigstore's keyless model** is why this became practical: instead of maintainers managing\nlong-lived signing keys (which historically nobody did well — see the PGP-on-PyPI\nexperience), you generate an **ephemeral keypair**, exchange a CI OIDC token with the\n**Fulcio** CA for a short-lived X.509 certificate binding that key to the CI identity, sign,\npublish the signature to the **Rekor** transparency log, and **throw the key away**. No key\nmanagement, and anyone can verify both the signature and the identity that made it.\n\n**Registry state as of 2026:**\n- **npm** — Sigstore-backed SLSA provenance, GA since 2023, generated by the npm CLI itself.\n- **PyPI** — **PEP 740** digital attestations, Final in 2024, generated automatically by\n  `pypa\u002Fgh-action-pypi-publish` v1.11.0+ when using trusted publishing. **Over 132,000\n  PyPI packages carried attestations as of March 2026.**\n- **crates.io** — trusted publishing is GA, but **Sigstore-based signing\u002Fprovenance\n  (RFC 3403) remains at the proposal stage**; integrity comes from elsewhere.\n- **Go** — arguably the strongest *integrity* story of any ecosystem via `sum.golang.org`,\n  but no build provenance; achieving higher SLSA levels goes through the build platform,\n  not the registry.\n- **Maven Central** — PGP signatures traditionally; Sigstore adoption is emerging and Java\n  provenance is the least mature of the major ecosystems.\n- **GitHub Artifact Attestations** provide a language-agnostic path (SLSA Build L2 by\n  default, L3 with reusable workflows), which is how ecosystems without registry support\n  get provenance at all.\n\n**[DURABLE, and the sentence to remember] Provenance does not prove a package is safe. It\nproves it came from the build pipeline its maintainers claim.** That is precisely enough to\ndetect the dominant 2025–26 attack pattern — a malicious version published from a stolen\ntoken outside the project's normal CI — and precisely not enough to detect a maintainer who\nwas themselves compromised (§8.1 → `package-manager-supply-chain-and-workspaces`).\n","# Package Manager Development: Registry Design, Cache, Layout, and Linking, Publishing and Authentication\n\n> **Part 2 of 5** of the *Package Manager Development* reference (plugin `package-manager-development`), covering §5–§7. Sibling skills: `package-manager-versioning-and-resolution` (§0–§4), `package-manager-supply-chain-and-workspaces` (§8–§10), `package-manager-ux-ecosystems-and-governance` (§11–§14), `package-manager-reference` (§15–§20). Section numbers are shared across the set; a reference written as §N → `skill` points into that sibling skill.\n>\n> **Currency:** Verified August 2026. See §17 → `package-manager-reference` for the currency snapshot and what goes stale first.\n\n> **How to read this.** Reference, not tutorial. Sections are independent. Three markers:\n> - **[DURABLE]** — computer science, or a lesson every ecosystem has independently learned.\n>   Does not expire.\n> - **[ECOSYSTEM]** — specific to npm, PyPI, crates.io, Go, etc. Verify against that\n>   ecosystem's current docs.\n> - **[CONTESTED]** — the ecosystems have made genuinely different, defensible choices, or\n>   the practitioners disagree. Both cases given.\n>\n> **⚠️ GOTCHA** boxes mark the design mistakes that produce unreproducible builds, wedged\n> caches, exponential resolutions, or supply-chain compromise.\n>\n> **The framing that organizes everything below: a package manager is a distributed\n> systems problem wearing a CLI.** It is a cache-coherency problem, a constraint-solving\n> problem, a trust-and-identity problem, and a compatibility-contract problem, all of\n> which happen to be invoked by typing `install`. Every serious difficulty in this\n> document is one of those four, and treating it as \"just downloading files\" is the root\n> of most bad designs.\n\n---\n\n## §5. Registry Design\n\n### 5.1 The API surface\n\n```\nGET  \u002Fpackages\u002F{name}                  → all versions + metadata (the resolver's hot path)\nGET  \u002Fpackages\u002F{name}\u002F{version}        → one version's metadata\nGET  \u002Fpackages\u002F{name}\u002F{version}\u002Fdl     → the artifact (usually a CDN redirect)\nPOST \u002Fpackages                         → publish (authenticated)\nDELETE \u002F POST \u002Fyank                    → yank\u002Funyank (NOT delete — see 5.2)\nGET  \u002Fsearch, \u002Findex, \u002Fchanges         → discovery and incremental sync\n```\n**Design notes that matter at scale:**\n- **Separate metadata from artifacts.** Metadata is small, hot, highly cacheable, and\n  resolver-critical. Artifacts are large, cold, and belong on a CDN. Conflating them makes\n  resolution slow (§3.6 → `package-manager-versioning-and-resolution`).\n- **Support conditional requests and incremental sync** (`ETag`, `If-None-Match`, a change\n  feed). Mirrors and CI caches depend on it.\n- **Paginate and bound everything.** A package with 10,000 versions must not return a\n  10 MB JSON blob on every resolution step.\n- **Publish upload timestamps** (Python's PEP 700 does) — this is what makes cooldowns\n  possible (§8.4 → `package-manager-supply-chain-and-workspaces`).\n\n### 5.2 Immutability — the single most important registry policy\n\n**[DURABLE] A published (name, version) must never change its bytes.** Consequences of\ngetting this wrong are severe and every ecosystem has learned it, usually the hard way:\n- Caches everywhere become incoherent.\n- Lockfile integrity hashes break for everyone.\n- The `left-pad` incident (2016) — an unpublished package broke thousands of builds —\n  established that **unpublishing must be tightly restricted**.\n\n**The correct primitive is a *yank* (or *quarantine*), not a delete:**\n- Yanked versions remain downloadable so existing lockfiles keep working.\n- They are excluded from *new* resolutions.\n- crates.io, PyPI (quarantine), and npm's deprecate\u002Funpublish windows all converge on this.\n\n**⚠️ And immutability has a security cost you must design for:** Go's `proxy.golang.org`\nand `sum.golang.org` provide extremely strong reproducibility — but that same immutability\nmeans **a malicious module version, once published and cached, persists and continues to be\nserved even after the source repository is removed.** Reproducibility and takedown are in\ndirect tension. Have a documented answer for it.\n\n### 5.3 Mutable-release poisoning — a live design problem\n\nEven with immutable versions, most registries historically allowed **adding new files to an\nexisting release** (e.g. a new wheel for a new Python version, months later). That's a\npoisoning vector: a stolen token lets an attacker add a malicious artifact to a\nlong-trusted release.\n\n**PyPI closed this in July 2026: new files are rejected on releases older than 14 days.**\nThe reasoning is instructive — the change was proposed during PEP 740 discussions in\nJanuary 2024, stalled, and was revived by the **March 2026 LiteLLM and Telnyx\ncompromises**. Before shipping, PyPI measured the impact: of the top 15,000 projects, only\n**56** had uploaded a Python 3.14-compatible wheel more than 14 days after the release\nfirst appeared. Seth Larson's stated rationale is worth internalizing: it prevents releases\nfrom entering \"an indeterminate and confusing state of both compromised and not\ncompromised, where only a subset of files could be poisoned.\"\n\n**[DURABLE] That's the template for registry policy changes: identify the vector, measure\nthe legitimate usage you'd break, publish the numbers, then change the default.**\n\n### 5.4 Namespacing and name allocation\n\n| Model | Example | Trade-off |\n|---|---|---|\n| Flat, first-come | npm (unscoped), PyPI, crates.io | Simple; **land-grab, typosquatting, permanent name exhaustion** |\n| Scoped\u002Fnamespaced | `@org\u002Fpkg` (npm), NuGet prefixes | Ties identity to an owner; reduces squatting |\n| Domain-derived | **Go** (`github.com\u002Fuser\u002Fmod`), Maven (reverse-DNS groupId) | Namespace is *inherited from an existing trust root*. Elegant; couples you to the host |\n| Content-addressed | Nix, Guix | Names are labels, identity is a hash |\n\n**[DURABLE] Go's and Maven's approach — deriving the namespace from a domain or repo you\nalready control — eliminates an entire class of problems** (squatting, name disputes,\nownership transfer ambiguity) at the cost of coupling package identity to a hosting\nprovider. If you're designing new, seriously consider it.\n\nWhatever you choose, you need policy for: name similarity (§8.3 → `package-manager-supply-chain-and-workspaces`), abandoned packages,\nownership transfer, trademark disputes, and reuse of deleted names (**never reuse a name —\nthat's the \"repojacking\" attack**).\n\n---\n\n## §6. Cache, Layout, and Linking\n\n### 6.1 The content-addressed store\n\n**[DURABLE] The right shape for a package cache is a global, content-addressed store.**\n```\n~\u002F.cache\u002Fpm\u002F\n  index\u002F         metadata, keyed by (name, version), immutable → cacheable forever\n  files\u002F         file blobs keyed by content hash (sha256)\n  packages\u002F      package trees, assembled from file blobs\n  tmp\u002F           staging — assemble here, then atomically rename into place\n```\nProperties you get for free: deduplication across projects, integrity verification by\nconstruction, safe concurrent access (a hash-named file either exists and is correct, or\ndoesn't exist), and trivial garbage collection.\n\n**Write atomically**: download to `tmp\u002F`, verify the hash, then `rename()` into place.\nA partially-written cache entry that looks complete is the classic \"wedged cache\" bug that\nusers fix by deleting the whole cache and cursing your name.\n\n**pnpm's contribution** was demonstrating how much this matters: a single content-addressed\nstore hard-linked into each project's `node_modules` means one copy of a given package\nversion on the whole machine, saving developers with many projects tens of gigabytes.\n\n### 6.2 The layout problem — four answers\n\nThis is the JavaScript ecosystem's defining argument, and it generalizes.\n\n| Layout | Mechanism | Ecosystem | Trade-off |\n|---|---|---|---|\n| **Nested** | Each package gets its own `node_modules` | npm v2 | Correct; enormous duplication; Windows path-length failures |\n| **Flat \u002F hoisted** | Everything flattened to the top, conflicts nested | npm v3+, Yarn Classic, Bun (default) | Compact, compatible; **allows phantom dependencies** (§6.3) |\n| **Isolated \u002F symlinked** | Content-addressed store + hardlinks + a symlink tree mirroring the true graph | **pnpm**, **Bun `--linker isolated`** | Strict — packages can only see what they declared; occasional postinstall scripts assume a hoisted shape and break |\n| **No node_modules** | A `.pnp.cjs` map from import to zip archive | **Yarn Berry PnP** | Fastest, strictest, \"zero installs\"; requires runtime cooperation and breaks tools that stat the filesystem |\n\n> **⚠️ GOTCHA — phantom dependencies are a correctness bug, not a style issue.** Under a\n> hoisted layout, `require('lodash')` works even if you never declared lodash, because\n> something else hoisted it to the top. Your code then breaks when that transitive\n> dependency changes — a failure with no visible cause in your own manifest. Strict layouts\n> exist entirely to make this impossible, and **that, not disk space, is their real\n> argument.**\n\n**[DURABLE] The generalizable lesson:** you're choosing between *the real dependency graph*\nand *a flattened approximation that the runtime finds easier*. Flattening is faster and\nmore compatible; it is also lying to the program about what it can see. Ecosystems whose\nruntime resolution is explicit (Python's `sys.path` per-venv, Cargo's compiler-passed\n`--extern`, Go's import paths) never had this problem, because the layout was never the\nlookup mechanism.\n\n### 6.3 Multiple versions coexisting\n\nIf your runtime can load two versions of the same package simultaneously (npm, Cargo), the\nresolver can escape most conflicts (§3.5 → `package-manager-versioning-and-resolution`) — at the cost of duplicated code, larger\nartifacts, and **singleton bugs**. If it can't (Python, Java on one classpath), a conflict\nis fatal and must be reported, which makes resolution failures far more common and your\nerror messages far more important.\n\nCargo's rule is a good middle: **semver-compatible versions are unified into one; semver-\nincompatible versions coexist.** This maximizes deduplication while keeping the escape\nhatch, and the \"expected `foo::Type`, found `foo::Type`\" error is the price.\n\n### 6.4 Runtime resolution is part of your design\n\nThe package manager's job doesn't end at install; the runtime has to find the code.\n- **Node**: directory walk up from the importer, looking for `node_modules` — the reason\n  layout *is* resolution.\n- **Python**: `sys.path`, one environment per virtualenv — flat, one version of anything.\n- **Cargo\u002FRust**: the compiler is passed explicit `--extern` paths — no filesystem search\n  at all, which is why Rust can have two versions of a crate without ambiguity.\n- **Go**: import path includes the major version (`\u002Fv2`) — **semantic import versioning**,\n  so two majors are literally different packages.\n- **JVM**: classpath order; first match wins. The source of endless \"jar hell.\"\n\n**[DURABLE] If you're designing a new ecosystem, make runtime resolution explicit and\nindependent of directory layout.** It removes phantom dependencies, path-length limits,\nand hoisting entirely.\n\n---\n\n## §7. Publishing and Authentication\n\n### 7.1 The evolution, and where it landed\n\n```\nGen 1  username + password                  → phishable, reused, no scoping\nGen 2  long-lived API token                 → phishable, exfiltratable, \"harvest now use later\"\nGen 3  token + 2FA on the account           → helps login, does NOT help a stolen CI token\nGen 4  TRUSTED PUBLISHING (OIDC)            → no long-lived credential exists at all  ★\n       + provenance attestations            → and the artifact proves where it came from\n```\n\n**[DURABLE] Trusted publishing is the current best practice and the direction every major\nregistry has moved.** The mechanism:\n1. The registry pre-registers a trust relationship: \"GitHub Actions workflow\n   `.github\u002Fworkflows\u002Frelease.yml` on repo `org\u002Frepo`, environment `release`, may publish\n   package X.\"\n2. At publish time, CI requests a short-lived **OIDC token** from its provider.\n3. The registry validates the token's claims (repo, workflow, ref\u002Fenvironment) against the\n   registration and issues a **short-lived, minimally-scoped** upload credential.\n4. No long-lived secret is ever stored anywhere.\n\nPyPI shipped this in April 2023; npm added it in response to Shai-Hulud; crates.io has it\nGA. **PEP 807** proposes standardizing the mechanism so *any* Python index can implement\nit, encapsulating PyPI's existing implementation.\n\n**Its explicit security properties**, as PEP 807 states them: credentials are short-lived\nand minimally scoped, limiting blast radius; automatic expiry means **attackers cannot\nmount \"harvest now, use later\" campaigns**; and the upload is conceptually linked to the\nCI identity authorized to perform it.\n\n> **⚠️ GOTCHA — trusted publishing is only as good as its trust configuration.** Trust by\n> *full repository*, not by org or wildcard. Trust by *branch or environment*, not by any\n> ref. A trusted-publishing config that accepts any workflow on any branch is worse than a\n> token, because it looks secure. The 2026 attacks specifically exploited this class of\n> misconfiguration.\n\n### 7.2 Provenance and attestations\n\n**The vocabulary, precisely — people conflate these constantly:**\n- **Provenance** = a *factual claim* about how an artifact was built (source repo, commit,\n  builder, parameters). **On its own it has no integrity properties whatsoever.**\n- **Attestation** = provenance wrapped in a *signed* envelope, so the claim has a\n  cryptographically verifiable author.\n- The dominant envelope is **DSSE** (Dead Simple Signing Envelope); the dominant payload\n  format is an **in-toto statement** with a **SLSA provenance** predicate. \"Attestation\"\n  in 2026 almost always means DSSE + in-toto.\n- **SLSA** describes build integrity *levels*; **Sigstore** is the signing mechanism that\n  makes the claims trustworthy rather than self-asserted text.\n\n**Sigstore's keyless model** is why this became practical: instead of maintainers managing\nlong-lived signing keys (which historically nobody did well — see the PGP-on-PyPI\nexperience), you generate an **ephemeral keypair**, exchange a CI OIDC token with the\n**Fulcio** CA for a short-lived X.509 certificate binding that key to the CI identity, sign,\npublish the signature to the **Rekor** transparency log, and **throw the key away**. No key\nmanagement, and anyone can verify both the signature and the identity that made it.\n\n**Registry state as of 2026:**\n- **npm** — Sigstore-backed SLSA provenance, GA since 2023, generated by the npm CLI itself.\n- **PyPI** — **PEP 740** digital attestations, Final in 2024, generated automatically by\n  `pypa\u002Fgh-action-pypi-publish` v1.11.0+ when using trusted publishing. **Over 132,000\n  PyPI packages carried attestations as of March 2026.**\n- **crates.io** — trusted publishing is GA, but **Sigstore-based signing\u002Fprovenance\n  (RFC 3403) remains at the proposal stage**; integrity comes from elsewhere.\n- **Go** — arguably the strongest *integrity* story of any ecosystem via `sum.golang.org`,\n  but no build provenance; achieving higher SLSA levels goes through the build platform,\n  not the registry.\n- **Maven Central** — PGP signatures traditionally; Sigstore adoption is emerging and Java\n  provenance is the least mature of the major ecosystems.\n- **GitHub Artifact Attestations** provide a language-agnostic path (SLSA Build L2 by\n  default, L3 with reusable workflows), which is how ecosystems without registry support\n  get provenance at all.\n\n**[DURABLE, and the sentence to remember] Provenance does not prove a package is safe. It\nproves it came from the build pipeline its maintainers claim.** That is precisely enough to\ndetect the dominant 2025–26 attack pattern — a malicious version published from a stolen\ntoken outside the project's normal CI — and precisely not enough to detect a maintainer who\nwas themselves compromised (§8.1 → `package-manager-supply-chain-and-workspaces`).\n",{"name":5,"description":7},"develop","ae32736a1aabddabca5d2c96d665aa0ebc7d8700","src\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fpackage-manager-development\u002Fskills\u002Fpackage-manager-registries-and-installation",3,"https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey","https:\u002F\u002Fthe-vibey-project.github.io\u002Fvibey\u002F","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project","https:\u002F\u002Fvibewithadam.matthewsteinberger.com","freedom for software engineers","2026-11-15 05:47:42",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add the-vibey-project\u002Fvibey --skill package-manager-registries-and-installation",{"tool":40,"command":41},"bunx","bunx skills add the-vibey-project\u002Fvibey --skill package-manager-registries-and-installation",{"tool":43,"command":44},"pnpm","pnpm dlx skills add the-vibey-project\u002Fvibey --skill package-manager-registries-and-installation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fpackage-manager-development\u002Fskills\u002Fpackage-manager-registries-and-installation\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7AT1FQJAE1FQYAMDTF490Y4","white-paper-writing","Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks \"how should I structure this\" for a long-form document.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fwhite-paper-writing\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7AT16BJRJJKK2MASXRZS76G","prose-technical-mechanics","Use when editing or writing prose at a technical\u002Fmechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-technical-mechanics\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7AT0W9HT0ZZ9Y287NW99MR3","prose-mechanics","Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate\u002FJamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix \"AI-sounding\" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-mechanics\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7AT0KR635JX66X2X6F3E2CP","narrative-structure","Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or \"how should I structure this story\u002Fpitch\u002Fpresentation\" request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fnarrative-structure\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7AT0AKGW09NKKZDYBT8VRDE","legal-brief-writing","Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic\u002Fneurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Flegal-brief-writing\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7AT00VWPS4Q8B5VEMXX9NQT","journal-publishability-criteria","Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs\u002Fpaper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fjournal-publishability-criteria\u002FSKILL.md",[],[]]